Tbpgr Blog

Recruiting Operations tbpgr(てぃーびー) のブログ

書籍 Effective Java | すべての公開API要素に対してドキュメントコメントを書く

パンくず

Effective Java
すべての公開API要素に対してドキュメントコメントを書く

概要

すべての公開API要素に対してドキュメントコメントを書く

詳細

公開APIは必ずJavaDocドキュメンテーションコメントを付与すること。
保守を意識するなら、公開しないメソッド等も出来る限りドキュメンテーションコメントを付与すること。

メソッドドキュメンテーションコメント

・どう行なっているかではなく、何を行なっているかを記述する。
メソッドの事前条件/事後条件を全て記載する。
・副作用がある場合はその内容も記載する。
・全ての引数は@paramに内容を記載する。
・戻り値は@returnに内容を記載する。
・例外の情報は@throwsに記述し、例外が発生する条件を記載する。
・ドキュメントコメントの最初の文は概要を表す。
メソッドごとに一意の内容になるようにすること。
必ず句点もしくはピリオドで終ること。

クラス、インターフェース、フィールド

・それぞれを表す事柄を説明する名詞

ジェネリック

ジェネリック型のコメントを記述すること

enum

・各定数にもコメントを付与することを忘れない

アノテーション

・各メンバーを文書化することを忘れない

JavaDocのタグについて
タグ 内容
{@literal} 不等号やピリオドをエスケープする
{@code} ソースコードを記載する
{@inheritDoc} 継承元の記載を流用する