[seasar-javadoc:691] Re: KPT org.seasar.framework.container.* 再び

Hideaki Suzuki suzuki @ uinet.or.jp
2006年 11月 9日 (木) 04:28:40 JST


鈴木(belltree)です。

DestroyMethodDefAwareのJavadoc … 私が書いてたのですね … orz

> JUNDOさん、コメントありがとうございます。
> いまのところ、get〜ところからは登録、追加を削除してしまいました・・・すいません。
> やっぱし、対話先がないのなら、かかない方がいい気がするのです。
> 
> 今日はこの辺で終了ですので、あったほうがいい案が多ければ、
> すいませんが、もどしちゃってくださいm_ _m

別人格になって、ちょっと考えてみました。(?_?;;;

たとえば、DestroyMethodDefAwareを実装しているComponentDefImplの
getDestroyMethodDefSizeのJavadocコメントを、Seasarファン(?)の人が
ピンポイントで見た時に、
※ eclipseでは、コメントが無いとインターフェースのJavadocが表示されます。
   @seeコメントの場合、@seeのメソッド名に、マウスカーソルを持っていくと、
   同じく、@see先のコメントが出ます。

 『終了メソッド定義の数を返します。』
と
 『登録されている終了メソッド定義の数を返します。』

それぞれどのように感じるかですが…

「登録されている」が付いている方が、
ComponentDefImplのインスタンスが、終了メソッド定義を所有している
こと(登録されていること)をより確実に伝えることができるため、ファンの人は、
より精密に、S2コンテナの状態を(この例の場合は、コンポーネント定義と
終了メソッド定義の関連を)イメージできるかなと思いました。

※ さりげなく destroyメソッド ⇒ 終了メソッド にしてます (^^;;

このへんは、想定読者をどんな人にするかによる部分かとも思うのですが、
以上を踏まえ「登録されている」付き に +0.5 (元は自分が書いたので控えめに…)

ただ、なんとなくですが、getDestroyMethodDefSizeの@return部分
  @return 登録されているdestroyメソッド定義の数
は、パッと見、冗長な気もします…でも、意味の伝達を重視すると、
やっぱりあった方がいいよなぁ〜むむぅ…
(どっちやねん!!!←ひさびさの自己ツッコミ)

座右の銘は SIMPLE IS BEST なのですが、このへんはさじ加減が難しいですね…。
特定範囲の想定読者を想像し、意味を正確を正確に伝える、
しかも必要十分な表現で… なんか、ある意味、芸術の香りがしてきました…
ううぅむ…万人受けする解説書とか書く人ってやっぱりすごいよなぁ…詩人ですよ

/** 
 * @auther Hideaki Suzuki
 * @contact suzuki at uinet.or.jp
 */



seasar-javadoc メーリングリストの案内