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

Hideaki Suzuki suzuki ＠ uinet.or.jp
2006年 7月 31日 (月) 02:35:10 JST 

鈴木(belltree)です。

パッケージ内の見直しフェーズ(仮称 seasar-javadoc KPT ^^;)について…

[seasar-javadoc:467] Re: ExternalContextComponentDefRegister
[seasar-javadoc:468] Re: ExternalContextComponentDefRegister
[seasar-javadoc:470] Re: ExternalContextComponentDefRegister
を踏まえ、やる方向ということで。 (^^


そんなわけで、いくつか思い浮かんだことを書いてみます。[Try]

■やりかた

・MLで 『KPT ComponentDef』というようなタイトルでスレッドを作り、
  みんなでそのJavadocの問題点、課題点を指摘しつつ見直していく。

・Javadoc記述についてパターン化できるものについてはパターン化し、
  Wiki上に、Seasar2の日本語Javadocパターン集を作る。

・類似クラス(インターフェース)は『〜Aware系』とか『Illegal〜Exception系』
  とかパターンに名前をつけて、記述サンプルをWikiに記載する。

・<code><var>{@link 〜} などの使い方についてもWikiの記述を充実
  させて、パターン化（名前を付ける？）と統一を図る。

・サインアップ表に『KPT完了日』の列増やして、ふりかえり完了日を入れる。

・修正は、原則として、オリジナルの担当者が行う。(これは議論の余地あり？)

・基本はみんなで見直すが、「日本語表現大臣(文部大臣?)」、「@see担当大臣」、
  「@throws担当大臣」など、見直す切り口ごとに担当を決めて、チェック漏れを
  防止する。 （これは微妙かなぁ…）


■見直す際の切り口

・内容の正確さ(想定する読者に誤解を与えない内容であるか？)
    …想定される読者像をある程度絞り込む必要あり？
    …Javaodcを読んで理解するために必要な前提となる知識や参考リンクを
       とかをJavadocのトップページに載せたりとか…？
    …そこまでやる必要はないかなぁ…とも思ったり

・日本語の表現
    …デスマ調…もとい、です/ます調になっているか？
    …国語のテストで赤点にならないレベルになっているか？（特に自分 orz）

・@seeの記述の適切さ
    …例外クラスであれば、例外が発生するメソッドを記述するとか

・@throwsの記述の適切さ
    …Wikiでは、「インターフェースで例外を記述するときは、実装クラス側で
       スローする可能性のある例外をすべて記述します。」となっているが、
       意外と守られていない可能性が… (特に自分… orz)

・@〜の記述順
    …以前、[seasar-javadoc:72] 参考資料(タグの記述順) で自分が
       「The Elements of Java Style」にあった内容を書いています。
       これも、どこまで統一するか検討が必要かも？

・理解の参考となるWebサイトのURLの記述 (いらないかも…)


なんかまとまってませんが…とりあえず、思いつくままに書いてみました。
「これはやりすぎでない？」という部分は、多々あるかと… (^^;;;
Javadocにも、ある程度個性が出てた方が、オープンソースっぽいし…(^^;;;

その他の見直しポイントや、やり方のアイデアなどありますか？


p.s.
サインアップ済みのソースで
「1ファイルだけど量が質に転化しちゃって難易度 激高」なものとか、
「ファイルは小さいけど、深い思想が必要」なものとか
現代社会の罠にハマリ
「とりあえず長期デスマ中で〜す♪」というケースとか
の場合のうまいサポート方法を考えたいですね。
※自分がそうなった場合に、サポートして欲しいからという噂も…

♪=1000(?)のデスマ中などの最悪ケースを除き、個人的には
「バトンタッチ」というか、LIFE CARD の 『あきらめる』カードのような選択は、
最終手段にした方がいいかなぁなんて…

せっかく有志が集まっているので、みんなでSeasar2の理解を深めて
いけるような方法で出来たらいいなぁと思いました。

例えば、Javadocのサンプルsnippetを提供したり、参考となるURLや本を
紹介したり「このクラスのコード読んでみソ」とアドバイスしたり/されたり。

ともあれ、あんまりプレッシャーとか考えずに、1行でも追加したら、
気軽にMLに投げてもいいのでは？質問とかも入れたりして…
(自分もComponentDefの時は、正直けっこう辛かったです…分からなくて…
 ていうか、今でも十分理解しているとは言い難いですけど… ^^;;;) 

長期デスマが予想される人は「SOS」メールを投げてもらえれば、きっと
誰かしら続きを書いてくれると思いますし…

なんてったって、Javadoc “チーム” ですから！！

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

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