Seasar2のドキュメントの件

単に、Seasar2のドキュメントが足りないだけだと、どのプロダクトのどこを指しているのかわからないので、改善が難しいのです。

Seasar2始めました - idesaku blog

id:higayasuo氏からのツッコミ。ごもっとも。disった以上、責任もってどこがわかりづらかったかあげたいと思う。

プロダクト名をあげると、S2ContainerとS2JUnit4

S2Container

S2Containerは、情報が無いというより、あるんだけど理解が難しい。もうちょいチュートリアル的なものと、サンプルコードが欲しい。

仕様は細かく書かれているので、ある程度全体を理解してからリファレンス的に参照する分は良いと思う。しかし、その仕様がひたすら文章で書いてあると(自動バインディングのルールに見られるような箇条書きの羅列部分とか)どうにも理解が難しく、とっかかりとしてはやはりサンプルコードと共にチュートリアルが提示されないとつらいように思える。

サンプルコードは、対になるdiconが提示されたほうが飲み込みやすいかと。自動バインディングがあるので、これに慣れないうちは何がどう連携してDIに達するのか(またはDIしないのか)よくわからない。

あと、これは他のプロダクトでも同じなのだが、サンプルコード中の"foo"みたいな意味のない文字列が理解を妨げる。
例えばマニュアル中に出てくる次のコードなのだが…。

@Binding("foo")
private Foo foo;

fooがコンポーネント名であることを即座に理解できなかった。無意味な名前なうえに、変数名と同じなところがまたたちが悪い。なにか変数名と関わりがあるのかと思ってしまう(あるんだっけ?ないよね?)。

S2JUnit4

S2JUnit4は、拡張されたassertXXX関係がわかりづらいと感じた。例えば、assertEntityEquals(DataSet, Entity)は単に「DataSetとEntityを比較する」と書いてあるのだが、まるで型が違う両者をどのように比較しているのかよく見えない(で、勘で使ってみるとNullPointerException...)。

あとは、やっぱりサンプルコードが簡素すぎるかなぁ、と。例えば、@Mock。

@Mock(target = Hello.class, pointcut = "greeting", returnValue = "'hello'")
public void hoge() {
    ...
}

作られたMockがどこにインジェクションされるのかさっぱりだった。もっとも、@Mockはテストメソッド実行直前に指定したコンポーネントにMockInterseptorを突っ込む、ということだけを定義しているので、それをどこにインジェクションするかは別問題だ。しかし、やはりぱっと見ではこのメソッドで定義したMockを使えるんだ、でもどうやって?と思うよね?

こう書くと使い方がわかっていいかもしれない?(間違っていたらごめん)

private Hello hello;

@Mock(target = Hello.class, pointcut = "greeting", returnValue = "'hello'")
public void hoge() {
    assertEquals("hello", hello.greeting());
    ...
}

ここまで書いて思ったが、結局チュートリアルが欲しいのだな、俺は。

こんなとこかな

そんなわけで、おおむねチュートリアルもっと欲しい!という話でした(?)

この記事書きながらいろいろ考えてみると、不慣れなうちは「暗黙の了解」がよくわからない - 記述足りない!と感じたようだ。ある程度理解した上で見直すと、情報は十分にあるのかもしれない。

いや、読みにくかろうが理解しづらかろうが、書いてあるんだから贅沢いってないでちゃんと読めよハゲ!と言われれば、まぁごもっともなのである。実際、俺は読んで理解までこぎ着けたし。しかし、ソフトウェア開発がチーム戦である以上、あまり技術に情熱が無い一般的エンジニア*1がさらっと読めて大づかみできねば困るわけで。

あ、SAStrutsS2JDBCチュートリアル揃っていてうれしいですね。

*1:一般的とは思いたくないが、現実は厳しい