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

[Hideaki Suzuki]

鈴木(belltree)です。

間があいてしまいましたが、コメントです。 (^^;;;

> > ・MLで 『KPT ComponentDef』というようなタイトルでスレッドを作り、
> >   みんなでそのJavadocの問題点、課題点を指摘しつつ見直していく。
> 
> 　なんとなくですが、またファイル毎の細かな単位にはならないような気が
> します。振り返り全体で１スレッド、またはこの後出てくるパターンごとに
> １スレッドとかではいかがでしょう。
そうですね。パターン毎に1スレッドに +1
すると、パターン単位で担当を決めて、そのグループのソースを、
その担当者が修正するという形になりますかね。

> > ・Javadoc記述についてパターン化できるものについてはパターン化し、
> >   Wiki上に、Seasar2の日本語Javadocパターン集を作る。
> >
> > ・類似クラス(インターフェース)は『〜Aware系』とか『Illegal〜Exception系』
> >   とかパターンに名前をつけて、記述サンプルをWikiに記載する。
> 
> 　このあたり、ちょっと私の考えは違いました。私の中ではWikiは全体に適用
> 可能な汎用化された内容を記述した方がいいのかなと思っていました。
> 
> 　なので、〜Aware系など別パッケージには出てくることが少ない気がするので、
> メールベースでやるのはどうでしょう。
> 
> 　ここは、Wikiの位置づけが個人ごとに違うかもなので、全体で方針を合わせた
> ら私もそれに従います(^^;
> 
> 　パターン分けには、私も賛成です。ちょっと試しに分けてみました（添付）
> まだ、他にもグループ分けの切り口があるかもしれません。
ML上で、パターングループ毎に『××Defのここは○○Defのこれに合わせる？』
的な意見を出し合って、すり合わせていく形ですかね… (^^
同時に複数のソースを評価していく方式だと、、グループに含まれるソースの
数を3〜4つくらい迄にしないと、大変かなぁ…
もしくは、グループの中で代表となるソースを決めて、それを標準化パターン
として調整してから(他のソースと比較しつつ)、グループ内の他のソースを修正
していく形がいいですかね？ M:N より 1:N の方が楽なので…
このへんは、やってみないと感覚が掴めないかもなぁ…

> > ・修正は、原則として、オリジナルの担当者が行う。(これは議論の余地あり？)
> 
> 　パターンごとに担当を改めて分けるという方法もありますね。
パターンごとに +1 です。

> > ・基本はみんなで見直すが、「日本語表現大臣(文部大臣?)」、「@see担当大臣」、
> >   「@throws担当大臣」など、見直す切り口ごとに担当を決めて、チェック漏れを
> >   防止する。 （これは微妙かなぁ…）
> 
> 　うーん、出来ると効率的そうですが、最初は難しい気もしますね(^^;;
大臣システムに -1 (^^;;; 確かに無理な気がしてきました。

> > ■見直す際の切り口
> >
> > ・内容の正確さ(想定する読者に誤解を与えない内容であるか？)
> >     …想定される読者像をある程度絞り込む必要あり？
> >     …Javaodcを読んで理解するために必要な前提となる知識や参考リンクを
> >        とかをJavadocのトップページに載せたりとか…？
> >     …そこまでやる必要はないかなぁ…とも思ったり
> 
> 　想定する読者というのは、ずっと気になっていました。読者は、ある程度
> あわせたほうが記述がブレ難い気もします。想定読者に縛られることは無い
> のかもしれませんが、想定読者が欲しい情報が書けたかというチェックの意
> 味で使うとよい気がします。
想定読者を例えば、
  ・Javaの基本を理解していること (あぃま〜い ^^ by SpeedWagon)
  ・DIの概念を理解していること
とするよりは、JUNDUさんが言われるように
『想定読者が欲しい情報が書けたかというチェック』の項目を具体的に
洗い出して、そのチェックシートを元に、評価していければいいかもですね。

というか、自分で言い出しておきながら、『想定読者』の限定がなかなか
難しそう…

なので、Wikiの方針の一部をブレークダウンしていく感じで、例えば…

  Javadoc は仕様を書くもの 
    → 仕様として記述されているか？
    →→ インターフェースの役割が明示されているか？
    →→ メソッドの入力項目/出力項目に関しての説明は十分か？
    →→ 曖昧な言葉(用語)を使用していないか？

  実装者の視点ではなく，利用者の視点で読めるように書く 
    → 利用者(読者)が理解し易い記述になっているか？
    →→ 必要に応じて箇条書きや表を使用して内容を整理しているか？
    →→ 関連したクラス/インターフェースの記述に漏れはないか？
    →→ 注意すべき点、例外的な部分が明示されているか？

などという感じで、チェックリストを作るのはどうでしょうか？
はじめから力まずに、進めていくなかでチェックポイントを増やして
いけばいいかもですけど (^^

> > ・日本語の表現
> >     …デスマ調…もとい、です/ます調になっているか？
> >     …国語のテストで赤点にならないレベルになっているか？（特に自分 orz）
> 
> 　私も… orz
ここは、もう、ガンバルしかないですね ^^;;; お互い気になる点をズバズバ
指摘しあうしかないかと…

> > ・@seeの記述の適切さ
> >     …例外クラスであれば、例外が発生するメソッドを記述するとか
> >
> > ・@throwsの記述の適切さ
> >     …Wikiでは、「インターフェースで例外を記述するときは、実装クラス側で
> >        スローする可能性のある例外をすべて記述します。」となっているが、
> >        意外と守られていない可能性が… (特に自分… orz)
> >
> > ・@〜の記述順
> >     …以前、[seasar-javadoc:72] 参考資料(タグの記述順) で自分が
> >        「The Elements of Java Style」にあった内容を書いています。
> >        これも、どこまで統一するか検討が必要かも？
> 
> 　この辺は、全部やった方がいい気がします。内容と違って、機械的に出来る
> ところですし。
ですね♪

> > ・理解の参考となるWebサイトのURLの記述 (いらないかも…)
> 
> 　ここは、想定読者次第という気がします。リンクの場合、リンク切れに対応
> する方法も考える必要が出てきますね。
いらないに +1 (蛇足多すぎ→自分 orz)

> > なんかまとまってませんが…とりあえず、思いつくままに書いてみました。
> > 「これはやりすぎでない？」という部分は、多々あるかと… (^^;;;
> > Javadocにも、ある程度個性が出てた方が、オープンソースっぽいし…(^^;;;
> 
> 　そうは言っても、可能な限り合わせたいですね。特にcontainerパッケージは、
> S2コンテナの顔(?)ですし。　がんばった結果、それでもバラツキが出るのは、
> 仕方ないと思います。J2SE1.4のJavadocも結構バラツキがありますし(^^;;
J2SE1.4のJavadocも結構バラツキがあるんですか…
なんかホッとしたりして ^^;; … ていうか、Javadoc読んでないのバレバレ? orz
てか、下を見ちゃいか〜ん！！！ (^^;;;;;


というわけで、JUNDUさん のパターン分けをベースに、KPTのやり方を
整理したいなぁと思ったりしました。けっこう内容が多岐に渡りそうなので、
Wiki上で一旦整理した方がよさげかなぁなんて…


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