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

9 冊目の著作となる本書は、ある意味私らしい「ややズレた」スタイルの書籍となりました。6/29 発売ですが、池袋ジュンク堂では本日先行入荷したそうです。

ちなみに、サブタイトルは「現場で使える API 仕様書の作り方」。Javadoc をテーマとした書籍は、恐らく世界初ではないかと。

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

本書は、意味のある Javadoc(ドキュメンテーションコメント)をほとんど見たことがないという現実を何とかしようと思って書きました。確かに、多くの Java のソースコードにはドキュメンテーションコメントが記述されています。しかし、その多くは「メソッド名の日本語訳」「引数名の日本語訳」といったもので、本当に意味があるものではありません。メソッド findCustomers() に「顧客を検索する」というドキュメンテーションコメントがあったところで、それが何だというのでしょう。findCustomers() というメソッドを見れば一目瞭然なのに、なぜわざわざメソッド名の日本語訳をつけるのでしょう。

ドキュメンテーションコメントが必要なのは、ソースを読んだだけでは分からないことを補足するためです。ソースコードを読めばわかることは、わざわざドキュメント化する必要はありません。しかしソースコードを読んだだけでは分からないことは、ドキュメントとして表現するしかないのです。そのようなスタンスで書いたとき、ドキュメンテーションコメントは初めて意味を持ちます。

そうは言っても、いきなり意味のあるドキュメンテーションコメントを書くというのは難しいと思います。そこで、本書ではチェックリスト形式で、「何を書けばよいか」「何を書かなければならないか」を説明することにしました。チェックリストといっても、そんなに細々としたものではありません。メソッド引数に対しては 7 つ、メソッド主説明に対しては 8 つ、クラスに対しては 13 程度です。いきなり全部を意識する必要はありませんので、分かるところ、納得できるところから使って頂ければと思います。

また、読みやすい API 仕様書(javadoc コマンドで生成した HTML ファイル群)を作るための基礎知識についても説明を加えました。javadoc コマンドを使って単純に API 仕様書を生成した場合、引数や返却値の型として「java.lang.String」といったものが登場してしまいます。この程度ならまだ許せるかもしれませんが、「org.springframework.context.ApplicationContext」のような長ったらしい型名が記述されていると、あまりの読み辛さにイライラしませんか? ほんの少し手間をかけるだけで、もっと読みやすい API 仕様書は生成できます。その「ほんの少し」のお手伝いをするのが本書です。

最終章では個人的な趣味に走って、Java で「契約による設計」を実現するためのライブラリ Contract4J5 を取り上げてみました。細かい説明が多く、紙幅の割に具体的な話には入れなかったのですが、一つの考え方として楽しんでいただければ幸いです。