パンくず
Effective Java
すべての公開API要素に対してドキュメントコメントを書く
概要
すべての公開API要素に対してドキュメントコメントを書く
詳細
公開APIは必ずJavaDocのドキュメンテーションコメントを付与すること。
保守を意識するなら、公開しないメソッド等も出来る限りドキュメンテーションコメントを付与すること。
メソッドのドキュメンテーションコメント
・どう行なっているかではなく、何を行なっているかを記述する。
・メソッドの事前条件/事後条件を全て記載する。
・副作用がある場合はその内容も記載する。
・全ての引数は@paramに内容を記載する。
・戻り値は@returnに内容を記載する。
・例外の情報は@throwsに記述し、例外が発生する条件を記載する。
・ドキュメントコメントの最初の文は概要を表す。
メソッドごとに一意の内容になるようにすること。
必ず句点もしくはピリオドで終ること。
クラス、インターフェース、フィールド
・それぞれを表す事柄を説明する名詞
enum
・各定数にもコメントを付与することを忘れない
アノテーション
・各メンバーを文書化することを忘れない
