「エンジニアのためのJavadoc再入門講座現場で使えるAPI仕様書の作り方」を読みました。

「エンジニアのためのJavadoc再入門講座」を読みました。

作者: 佐藤竜一
出版社/メーカー: 翔泳社
発売日: 2009/06/30
メディア: 単行本（ソフトカバー）
購入: 15人クリック: 263回
この商品を含むブログ (49件) を見る

正直読む前は「エンジニアのためのWord再入門講座」が当たったから二匹目のドジョウを狙って書いたんかな、Javadocタグの使い方の説明くらいかな、程度に思っていましたが、ふと読んだら超良書でした。3章と4章が重要（この本にしかないノウハウ）です。

この本はSI屋の人にわかりやすくいうと「Javadocに書くべき設計項目の一覧*1」です。

最近は「プログラム設計」*2の無意味さの理解が広まってきたのでやらないことが多いですが、設計書は不要であっても設計自体は必要です。そしてその結果はクラスやメソッドの外部仕様としてJavadocに書かれます。その意味でJavadocは設計書なのですが、Javadocタグは知っていても何を書くべきかは割と人に依存していることが多いです。
ここでいう「何を」とは@Paramsや@Exceptionという粗いレベルではなくて、たとえばこんなこと。

List findCustomers(String name)メソッドを実行したとき、顧客が存在しなかった場合はどうするべきか
A. nullを返す
B. 空のリストを返す

この質問を著者があるセミナで会場に問うたところ、2対1でBが多かったそうです*3。誰にとっても共通的な判断基準はないので、APIの仕様書であるJavadocにはそういった観点の記述を盛り込むべき（顧客を検索する、とかじゃなくて）です。この本ではその観点を紹介しています。

本書のもっとも重要な節はこの3つです。

3.3 引数／返却値／例外の説明として記述すべきこと
4.2 インターフェースのドキュメントに求められるもの
4.3 クラスのドキュメントに求められるもの

上記は各要素に対して「何を」書くべきかのチェックリストになっています。チェックリストの内容はこの本の核なので著者に敬意を払って引用はしません。たとえチェックリスト自体を引用されても3章、4章は各項目の背景や意味を詳細に説明してあるので、すべて理解するにはきちんと読む必要があります。

ただ、結構厚めの本なのですが、本書で重要（この本にしかないユニークな部分）なのは3章と4章のみです。
1, 2章はJavadocの基本的な部分の説明です。これは前提知識なので知らない人には必要ですが本書にしかない部分ではないです。
5章はJavadocの他のタグ等を説明していますが、大体がJavadocの説明になっています。Java5からのタグも紹介されているので知らない人は読む価値が有ります。
6章はContract4J(契約による設計をJavaで実装するためのフレームワーク)の説明です。主題と関連はあるのですが本旨ではないです。*4

この本は2500円程度するのですが、3章と4章だけでそれ以上の価値があります*5。

ちなみに冒頭で挙げた「エンジニアのためのWord再入門講座」も良本です。