TOP
＞
システム開発
＞ Java開発に役立つ「Javadoc」
Javadocから考える開発ドキュメンテーション
第１回：Javadoc、どのくらい活用していますか？
著者：
ウルシステムズ 足立 祐一
2007/8/17
1
2
3
次のページ
Java開発に役立つ「Javadoc」
Javaで開発を行っていると、ライブラリのリファレンスとしてJavadocを参照することが多いはずです。ただ参照するだけでなく、場合によっては携わっているプロジェクトなどの開発規約でドキュメンテーション規約としてJavadocを記述することが定められているケースもあると思います。
筆者はオープンソースのライブラリを使用するときよりも、内製のライブラリや同じプロジェクトで他の人が作ったクラスを利用するときのJavadocの質の悪さに閉口した経験があります。皆さんも例えばこんな経験はないでしょうか？
書いてある通りに使っただけなのに、いきなり例外が飛んできた
Javadocが書いてあったりなかったりで、使い方がわからない
関連したクラス間で、矛盾したことが書いてある
Javadocが書いてあるけど、有用な情報がない。クラス名やメソッド名、引き数名もピンと来ないし……ソースを見るか
Javadocを見ながら作ったんだけど内容が古く、しかも結合テストまでわからなくて大修正する羽目になった
表1：Javadocでありがちな経験
これは読む側の視点です。では、自分がJavadocを書く立場となったらどうでしょうか。コーディングや度重なるデバッグに追われて、後回しにしてしまったり、読む人に対して気を遣っていなかったりするのではないでしょうか。
それだけではありません。保守する人すべてが正しく維持しておく意識を保っておかないと、最初は適切に書かれていても、メンテナンスをされているうちに実体と乖離してしまって次第に荒れていってしまいます。ソースコードならばリファクタリングなどで秩序が失われていくことを防止する必要性がよく知られています。これと比べると対照的です。
では、Javadocは書くだけ頭痛の種が増える必要悪なのでしょうか。
そんなことはありません。開発者が作成する成果物でソースコードは重要ですが、継続的に面倒をみていくためには人と人とのコミュニケーションが必要であり、ソースコードだけでは不十分です。Javadocの特徴を再認識し、もっと開発プロセス全体に視野を広げて活かすことが重要なのです。
後述しますが、JavadocにはコメントからHTMLを生成する以外にも機能を拡張することができます。本連載ではJavadocのよさ、ドキュメントとして書くべきこと、そしてJavadocの基本的な仕様を再確認してからJavadocを有効活用するための工夫をいくつか紹介していきます。さらにそのノウハウを開発に必要なドキュメンテーションへと展開していきます。
1
2
3
次のページ
著者プロフィール
ウルシステムズ株式会社 足立 祐一
コンサルタント
Javaを中心にアーキテクチャ設計〜アプリケーション開発に従事し、製造業界、金融業界のSIerを経て現職。新しい技術、古い技術を駆使し、お客様の課題をITによって解決できるシステムを提供すべく、日々奮闘中。
INDEX
第1回：Javadoc、どのくらい活用していますか？
Java開発に役立つ「Javadoc」
Javadocの特徴
2つの視点からみるJavadocの足りない点
