エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方 - 佐藤竜一

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

★★★☆☆
以前は HTML に起こす事を考えてちょっと頑張ってみたりしてたけど、ソースの数が膨大になったのもあって HTML を起こす事を意識して書く事は無くなってしまった。
製品としていろんな人がみるならまだしも SI で個別に作ってるものに対してみんなどれぐらい力を入れて作ってるんだろうか？僕の場合はもう

/**
* ○○するメソッドです。
* これは○○で△△であるため××です。
* 使いかたは
*   A a = new A();
*   a.method();
*
*/
public void method() {

こんな感じでソースを開いてみる事を前提に書いちゃってる状態。本書に

クリアなコードを書くためには、コードもドキュメントの一つとして真剣に扱う必要がある

とあったのでちょっと考えを改めようと思う今日この頃。
パターン別にチェックポイントがあって、どう書けばいいのかが載っているので一読してみた方が良いと思う。
最後は Contact4J5 の説明で何となく終わった感じなのがちょっと残念ではあった。