ドキュメンテーションコメントからプログラミングを考える / 『エンジニアのためのJavadoc再入門講座』を読んだ

『エンジニアのためのJavadoc再入門講座　現場で使えるAPI仕様書の作り方』を読んだ。

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

ソースコードの書き方、コメントの書き方を説明している書籍は、『リーダブルコード』をはじめとして数多く存在するが、ドキュメンテーションコメントに焦点を当てている書籍は珍しい。

タイトルにあるように、この書籍はJavaにおけるドキュメンテーションコメントの仕組みであるJavadocを扱ったものである。内容も、多くはJava、あるいはJavadoc固有の事柄が中心だ。しかし、広くドキュメンテーションコメントの書き方、ひいてはコードの書き方や設計の考え方にも役立つ内容も多く含まれていた。

Javadocとは？

Javadocは、JavaのソースコードからAPI仕様書を生成する仕組みだ。クラスやメソッド等の宣言の上部に/** コメント */という形で記載しておいたコメント（ドキュメンテーションコメント）を元に、コマンドひとつでHTML形式のAPI仕様書を生成することができる。書籍から具体例を引用しておく*1。

/**
 * <p>指定された顧客名の合致する顧客の一覧を返します。
 * <p>顧客の姓と名を1文字のスペース（U+0020）で結合し、
 * その結果が引数に指定された顧客名に前方一致した場合、
 * その顧客は結果のリストに含まれます。
 * @param name 顧客名
 * @return 顧客の一覧（順不同）。一件も合致しなかった場合は空のリストを返す。
 * @exception IllegalArgumentException 顧客名が{@code null}、
 * または空文字列だった場合
 */
public List<Customer> findCustomers(String name)
  throws IllegalArgumentException;

上のコメントを書くことによって、下記のようなHTML文書を生成することができるほか、IDE（例はEclipse）でマウスカーソルを当てた際に表示されるツールチップの情報を充実させることができる。

f:id:ky_yk_d:20190106214017p:plain — 生成されるHTML文書

f:id:ky_yk_d:20190106235851p:plain — Eclipseで表示されるツールチップ

なぜ「ドキュメンテーションコメント」か？

この書籍では、ドキュメンテーションコメントを、通常のコメントとは異なる役割を持つものとして捉えている。すなわち、通常のコメントが「人間がそのソースコードを読むための補助情報」であるのに対し、ドキュメンテーションコメントは、「コードから独立したAPI仕様書として読まれる」ものだというのだ。

ドキュメンテーションコメントはAPI仕様書を作成するためのものであり、記述すべきなのは、「仕様」である。もちろん仕様は、クラスやメソッドの名称や引数（シグニチャ）から推測することもできるし、細かい動きが知りたければ、ソースコードを読めば理解することができる。

しかしながら、シグニチャだけでは（特に特殊なケースの）振る舞いについて情報が不十分である場合が多いし、いちいちソースコードを読むのはコストがかかりすぎる。そこで、ドキュメンテーションコメントという形で仕様についての情報を補う必要がある。

ドキュメンテーションコメントの意義の二側面

プログラムの仕様が、ドキュメンテーションコメントによって明確になることは、多くのメリットを生み出す。この書籍では、下記のようなものが挙げられている。

クラスの目的が明確になることで、そのクラスの用途がわかり、再利用性が増す
クラスの制約が明確になることで、そのクラスを使ってはいけない局面がわかり、無用なバグを減らすことができる
正しく文書化されたクラスは、利用する側の学習コストを低く抑えられる

これらは、一度作られたプログラムに関わるメリットである。しかし、著者は同時に、ドキュメンテーションコメントの記述対象となるプログラムの作成段階で得られるメリットにも言及している。それが下記の3つである。

設計の漏れや抜けを削減できる
クラスやメソッドの設計品質が上がる
テストケースの設計が行いやすくなる

この後者の側面が、この書籍の面白い部分だと思う。仕様を明確に表現するドキュメンテーションコメントを書く（書こうとする）と、実装者自身の曖昧な理解、設計の漏れや歪さに気づくチャンスが生まれる。コメントを書く段階で仕様を明確にできれば、テストも書きやすくなる*2。

優れたプログラマであれば、ドキュメンテーションコメントを書くまでもなく、漏れや曖昧さのない設計・実装をすることができるのかもしれない。しかし、少なくとも僕のような経験の浅いプログラマにとっては、自分が書こうとしているプログラムについて吟味する機会は不可欠だ。この書籍を読むことによって、自分が意識してなかったプログラミングの観点を知ることができた。

ドキュメンテーションコメントのチェックポイント（抜粋）

ドキュメンテーションコメントを書く際のチェックポイントは、第3章・第4章で数多く挙げられている。一部を抜粋して下に記載しておく。

メソッドの引数
- 典型的な「特別な値」を受け取ることは可能か？
- 定義域内に「穴」となる値は存在しないか？
- 受け取ったオブジェクトの状態は変更されるか？
メドッドの返却値
- 定義域のすべての範囲に対して、適切な返却値が定義されているか？
- 返された値を、呼び出し側でチェックする必要はないか？
メソッドのスローする例外
- 例外が発生する状況がわかるようになっているか？
インターフェース
- そのインターフェースがコラボレーションすべきオブジェクトは明確になっているか？
クラス
- クラスの生成や破棄に、特別な手続きは必要ないか？
- そのクラスは、他の類似のクラスとは異なる振る舞いをしないか？

出版社のHPで公開されている目次も参考になると思う。

www.shoeisha.co.jp

感想

この書籍は、ドキュメンテーションコメントについて書かれたものだ。しかし、ドキュメンテーションコメントを書こうとすることは、先に述べたように、考えるという営みを伴うものであるし、ドキュメンテーションコメント以外の、ソースコード本体や通常のコメントで書くべき事柄を浮き彫りにすることでもある。多くを学び、また学ばなければならないと感じさせられた。

また、この書籍で一つの考え方として紹介されている「契約による設計」についても、理解を深めたいと思った。外見も値段もゴツいバートランド・メイヤーの『オブジェクト指向入門』は、読みたい読みたいと言いながら読めていない。平成のうちに読めるだろうか。