Javadoc の書き方

Java

　みなさん、Javadoc 書いてますか？　Javadoc は「API ドキュメント」と言われることが多いように、主にライブラリ的なプログラムで書いてこそのものだと思っている方もいるかもしれません。しかしながら、仕様書を Word や Excel（笑）で別途作ると、プログラムと仕様書の同期がとれてないというはめに陥り易くなりますので、Javadoc はどんなときも活用したいというのが私の考え方です。

まず、overview.html を書け

　Javadoc コメントをいくらか書くような人でも、overview.html を書く人は意外と少ないのではないでしょうか。リファクタリングが何度となく行われるアジャイル開発の現場では、クラスの構成がよくかわりますので、いちいち詳しいコメントを書いていられないということはあるかもしれませんが、overview.html はそれほど何度も手をつけるようなものではないので、早めに書いてしまいましょう。

　念のために補足しておきますと、overview.html とは Javadoc で生成したドキュメントの「概要」のページで、トップページとして採用されるページです。

　overview.html には、以下のことを書きます。

  • この Javadoc ドキュメントはなんのドキュメントなのか。例）このドキュメントは、○○社向け△△△システムの API ドキュメントです。
  • この Javadoc ドキュメントの対象となるプログラムは何をするものなのか。
  • どんなプロダクト（フレームワーク等）を使っているのか。
    • DI コンテナ、Web アプリケーションフレームワーク、テンプレート、O/R マッパ等
    • Maven を用いていれば細かい依存ライブラリの話は Maven が生成する Project site に逃してしまってもいいかと。

そして package-info.java を書け

　クラスの構成ほどかわらないのがパッケージです。ですので、このパッケージのコメントも早めに充実させてしまいましょう。特に私が気を使うのは、Seasar の SMART Deploy を使っている場合、service、logic、helper のそれぞれの役目を明確にすることです。

　何年か前のエントリで、これらの違いを教えてもらったのですが、その時の状況と現在の状況は違う（S2AbstractService が業務ロジックを表わしているとは思えない）ので、結局「決め」の問題なんだと思うのですよ。

　ちなみに私のパッケージの分け方はこんな感じです（Cubby と S2JDBC を使用）

action
Action クラス。機能のまとまりごとにサブパッケージを作ることもある。
entity
S2JDBC のエンティティ
service
S2AbstractService のサブクラス。基本的に 1 エンティティに 1 クラス、1 メソッドに 1 SQL。なので JOIN によって複数のエンティティを取得することはあっても、複数回 SQL を投げて複雑なリストを作るといったことはしない。ロギング以外の目的で INSERT も UPDATE も DELETE もオーバーライドしないし、新たにそれを目的としたメソッドは追加しない。ただし RDBMS に依存せずにカスケード更新、カスケード削除したい場合はここで対応する。
logic
1 リクエストに対応する業務要件を満たすのに service の 1 メソッドでは対応できない場合に作成。基本的に 1 サブアプリケーションに 1 クラス。1 リクエストに 1 メソッド。エンティティの操作は原則として service のメソッドを使用。
helper
特別なファイル入出力、ネットワーク接続等、環境・設備への依存性の高いものを置く。目安としては IOException を自分で処理しなくてはならないような処理。処理のかたまりごとにクラスを作成。
util
ユーティリティクラス。できるだけ Jakarta Commons を頼るようにしているが、それでも足りないときに自作したものを置く。static メソッドのみのクラスを置くため、DI コンテナでは管理しない。
validator
自作のバリデータ置き場。
misc
その他。Generics のせいで Collections 系の型の指定が面倒くさいと思ったときのラッパークラスや、エンティティじゃないんだけどちょっと値を保持するようなクラスが欲しいときに置く。

最後にクラスやメソッドのコメントを整備せよ

　どのような処理をしているのかを書くのはもちろんですが、特に Javadoc ではアノテーションがどうついているかがわからないのでそれを補完するように書くようにします。また、デフォルトコンストラクタで特に何もすることがなくても、デフォルトコンストラクタを定義することをおすすめします。なぜならば、ドキュメントを生成してみると「未稿」なのか「未定義」なのかがわからないからです。ちょっと面倒くさいと感じるかもしれませんが、Eclipse のコードテンプレートを使うと、そうでもないです。

　以上を踏まえたうえで、クラスの Javadoc コメントは以下に注意して書きます。

  • リクエストパラメータはどれなのか
  • UIとして期待するのはどのようなものか（HTMLの入力フォームはどのようになるか）
  • どんなリクエストパスに対応しているのか
  • どのバリデーションルールを使用するのか
  • バリデーションで不合格となった場合どこにフォワードするのか
  • どんなバリデーションを行っているのか（表で書くと書きやすい）
  • アクションの正常終了時のフォワード/リダイレクト先
  • インジェクションされることを期待しているのか
  • インスタンスタイプがデフォルトと違う場合はインスタンスタイプも明記。


以上のことに従えば、Javadoc ドキュメントはかなり心強い仕様書となることでしょう！