エンジニアのためのJavadoc再入門講座

私が敬愛するエンジニア、id:riueこと佐藤竜一さんの最新著作です。いつもながらのすごい着目点。Javadocを題材に一冊書いてやろうなんてことは、なかなか思いつかないです。そして執筆ペースもすごい。執筆は主に土日を使うそうですが、それにしてもすごい集中力です。

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

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

さて、おそらく私も含めJavaでの開発経験がある方は、Javadocに多少なりともお世話になっているはずです。ただ、本書に書かれたレベルでしっかり書いたことのある人は少ないんじゃないか?少なくとも私も含め受託開発の現場ではそう感じます。なぜならまだ、JavadocによるAPI仕様書が納品物として認められていないことが多いからです。形だけの量を稼ぐための納品物になっちゃったり。。
プログラマとしてもちろんJavadocはしっかり書くのですが、それがその後活かせないとあるとしっかり書くモチベーションが下がり、ついつい適当な「メソッドの日本語訳ドキュメント」になってしまう。これは私にも経験があります。
このような状況を現場で感じているであろう筆者は、Javadocを形だけの成果物から、本来の目的である仕様を正しく記述するためのドキュメントに引き戻そうとしてます。本書は、Javadocという手段の使い方を説明するものではなく、仕様はこのように書くべきだという主張が詰まっている本です。
私は、本書に書かれた視点で昔自分の書いたJavadocを見直してみると、いかに「雰囲気で」書いたものか実感できました。Javaで仕事をしている人は、一度本書に目を通しておくとよいでしょう。