Javadoc、どのくらい活用していますか？

Java開発に役立つ「Javadoc」

Javaで開発を行っていると、ライブラリのリファレンスとしてJavadocを参照することが多いはずです。ただ参照するだけでなく、場合によっては携わっているプロジェクトなどの開発規約でドキュメンテーション規約としてJavadocを記述することが定められているケースもあると思います。

筆者はオープンソースのライブラリを使用するときよりも、内製のライブラリや同じプロジェクトで他の人が作ったクラスを利用するときのJavadocの質の悪さに閉口した経験があります。皆さんも例えばこんな経験はないでしょうか？

これは読む側の視点です。では、自分がJavadocを書く立場となったらどうでしょうか。コーディングや度重なるデバッグに追われて、後回しにしてしまったり、読む人に対して気を遣っていなかったりするのではないでしょうか。

それだけではありません。保守する人すべてが正しく維持しておく意識を保っておかないと、最初は適切に書かれていても、メンテナンスをされているうちに実体と乖離してしまって次第に荒れていってしまいます。ソースコードならばリファクタリングなどで秩序が失われていくことを防止する必要性がよく知ら れています。これと比べると対照的です。

では、Javadocは書くだけ頭痛の種が増える必要悪なのでしょうか。

そんなことはありません。開発者が作成する成果物でソースコードは重要ですが、継続的に面倒をみていくためには人と人とのコミュニケーションが必要であり、ソースコードだけでは不十分です。Javadocの特徴を再認識し、もっと開発プロセス全体に視野を広げて活かすことが重要なのです。

後述しますが、JavadocにはコメントからHTMLを生成する以外にも機能を拡張することができます。本連載ではJavadocのよさ、ドキュメントとして書くべきこと、そしてJavadocの基本的な仕様を再確認してからJavadocを有効活用するための工夫をいくつか紹介していきます。さ らにそのノウハウを開発に必要なドキュメンテーションへと展開していきます。