[seasar-javadoc:520] Re: KPT org.seasar.framework.container.*

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Tue, 22 Aug 2006 17:22:17 +0900
From:    "Jundo Ishikawa" <jundo.ishikawa ＠ gmail.com>
To:      seasar-javadoc ＠ ml.seasar.org
Subject: [seasar-javadoc:519] Re: KPT org.seasar.framework.container.*

> 　JUNDUです。Javadocの内容チェック用に想定する読者というかチェックポイントを
> 少し考えてみました。

ありがとうございます♪

> 一般論的になってしまいますが、こんな感じでいかがでしょう
> か？
> 
> 共通して必要なもの
> ・クラスの責務
> 　→そのクラスの仕事は何か。何のために存在するのか。
> 　→そのクラスではやらないことは何か

「やらないこと」は難しそうですね．(^^;

> ・処理内容
> 　→どうやるかではなく、何をするか。

これは (特にインタフェースでは) 重要ですね．

> ・事前条件
> 　→引数とクラスの状態。投げられる例外。
> ・事後条件
> 　→戻り値とクラスの状態が変わる場合はクラスの状態。

これは真剣に書こうとするととっても大変そう．(^^;
事前条件はエラーチェックとかあればまだ楽ですが，
事後条件はかなり深くコードを読んでいかないと書ききれないかも．
もっとも，事後条件こそがそのメソッドの責務なので，書けるなら
書いた方が望ましいとは思います．
これは労力との兼ね合いになりますかねぇ．

> 想定する読者と求めるもの
> ・Seasar2の一部機能を使うためにソースを読もうと思った人。
> 　→使いたいと思ったクラスの使い方サンプル。
> 　　主にUtilパッケージ配下とS2ContainerやS2SontainerFactoryなど。

他には Interceptor や S2Extension (特に S2JDBC) がこれに
該当しますね．
できれば，こういう人がソースを読まなくても Javadoc を
見るだけで済むようにしたいです．

> ・Seasar2の機能を拡張して新しい機能等を作成することを考えている人。
> 　→拡張可能なポイントと拡張時の注意点。
> 　→IntercepterやInterTypeなどの骨格実装クラスの説明。

container.impl.S2ContainerBehavior などもこれに該当しますね．
個人的には，ココまでの二つを特に重視したいかなぁ．

> ・Seasar2でトラブルがあり、ソースを読むことになった人。
> 　→必要最小限のところを読むために、大まかな構成。
> 　→各メソッドの大まかな処理内容。
> 　→例外の発生原因？
> 
> ・Seasar2の理解を深めるためにソースを読もうと思った人。
> 　→クラスの関連図（サンタさんのプレゼント強化版）
> 　→クラスの関連の説明（パッケージコメント）
> 　→Diconファイルとソースの関連性。
> 
> ・Seasar2の使い方を知るためにソースを読もうと思った人。
> 　→Seasar2のドキュメントとソースの関連性？
> 　→Diconファイルとソースの関連性。

これらの人達はソースを読まないといけないわけですが，その場合に
期待される内容は，最初の二つとは随分と違いそうです．

> 　Seasar2のようなDIコンテナの場合、コンテナに依存しないコードを書くのが普通な
> ので、どういう内容を書いたらいいのか（期待されているのか）が悩みどころですね。

そうですね，実際「ココが分からない」っていう意見が出てこないと
気づかないこととかありますからね．
でもでも，これまで皆さんが書いてくれた Javadoc にしても，
コードを書いた本人には書けない (書くべきだと気づかない) ことが
たくさん盛り込まれてるって話をひがさんとしたことがあります．
皆さんの視点で書き進めてもそんなに外すことはないのではないかと．

> 　上に上げた中では、拡張のための情報がコミッタの方々のご協力を仰がないと難しい
> 気がしました。他のものも漏れなく書くのは大変だと思いますが、志は高くということ
> で(^^;

Javadoc チームもコミッタだとか書いてみるテスト．(^^;
ともあれ (JW)，協力は惜しむこと無くやっていきますのでご安心ください．


-- 
<component name="koichik">
    <property name="fullName">"Koichi Kobayashi"</property>
    <property name="email">"koichik ＠ improvement.jp"</property>
    <property name="blog">"http://d.hatena.ne.jp/koichik"</property>
</component>