Javadocコメントチートシート

先日、書店で見かけて衝動買いした本。
javadocは今まで曖昧な部分があったので、本書をベースにまとめておきたいと思う。

本の読書感想文はそれはそれで別途まとめておきたい。

観点編

書くときの原則

最低限守るべき事

  • 情報のない単なる和訳はつけない
  • 1行目はシンプルに概要レベルの内容を記述

DbC

契約による設計(Design by Contract)を定義すること。

事前条件呼び出し元の不正入力範囲外だった場合は動作を保証しない事後条件呼び出し先の不正条件を満たさない場合、呼び出し先のバグ不変条件オブジェクトの不正条件を満たさない場合、オブジェクトのバグ

記述に関する注意

  • HTML形式で記載する。
  • 段落表現は<ul>,<li>で箇条書きを表現する。・「中黒」は使わない。
  • <,>などの特殊文字はHTMLでは、&lt; や &gt;に変換されるので、@literalで表現する。

タグの使用についてのTIPS

  • @code:コードをコードとして記述するために使う。※詳細は後述
  • @value:定数へのコメントで使用する。定義値が@valueに挿入される。
  • @see:関連項目をブロックタグとして表現する時に使用する
  • @link:関連項目をインラインリンクとして表現する時に使用する

@codeのタグで使用すべき文字列

javaの予約語public, private, null・・・プリミティブ型chara, int, boolean・・・パッケージ、クラス、メソッド、フィールド等の名称メソッドの引数名args, str, regex・・・

ブロックタグとは?

@param:hogeの様に文頭から始まる。
メソッドパラメータ、返却値、例外、関連項目などを記述。

インラインタグタグとは?

{@code null}の様に文中に記述する。
null@linkを表現したいときに記載する。

クラス

存在意義

外部から呼ばれる部品として、目的役割を明確にしておく。

観点一覧

めっちゃ多い。
特に気になるのは、状態に関する事とスレッドセーフかどうかです。
ロールとか概念はクラス名で取って代わっても良いような気がします。

そのクラスが担うべきロールは明確になっているか?
クラスの生成や破棄に、特別な手続きは必要ないか?
そのクラスが表現する概念に、あいまいさは残されていないか?
「実装上の都合」で作らなければならないクラスではないか?
状態に関する情報は盛り込まれているか?
そのクラスは、他の類似のクラストは異なる振る舞いをしないか?
直観に反するような振る舞いをするクラスではないか?
クラスはスレッドセーフか?
クラスを利用する上で、何らかのサンプルは必要ないか?
OSやハードウェアに依存する部分はないか?
そのクラスの挙動は、外部の仕様によって説明されていないか?
既知のバグについての説明はあるか?
クラスの型パラメータは示されているか?

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第4章、095項、3段落)

インタフェース

存在意義

クラス(実装)より抽象的な存在。あるべき姿を記載しておく。

観点一覧

インタフェースなので、クラスよりふわっとした内容です。

処理内容を定義するというより、原則的にどこまでカバーするべきかを記載します。

そのインタフェースがコラボレーションすべきオブジェクトは明確になっているか?
インタフェースの一般原則が示されているか?
定義の中に、さらに定義を要する用語は含まれていないか?
実装を意識した記述になっていないか?
実装における許容範囲は示されているか?
mixin的にインタフェースの場合、それを実現することによるメリットは挙げられているか?

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第4章、087項、3段落)

メソッド

存在意義

主説明、引数、返却、例外からなる。部品のコアなので各項の観点を抑える。

観点一覧:主説明

仕様を書くべき。
特に、副作用とか制約についてはきちんと書いた方が幸せ。

そのメソッドが「何を行うものか」が書かれているか?
そのメソッドを呼び出す前に、しておかなければならないことはないか?
そのメソッドを呼び出せない局面というものはないか?
そのメソッドを呼び出すことによって、副作用は発生しないか?
メソッドの呼び出しが失敗した場合に、何か困ったことは起きたりはしないか?
そのメソッドを呼び出すことによって、後戻りできなくなるようなことはないか?
メソッドシグニチャからは決して読み取れないような制約はないか?
呼び出し元で意識しなければならない、実装上の都合はないか?

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第3章、067項、3段落)

観点一覧:引数

定義値についての厳密性と、範囲外だった時の挙動は書いておくべき。


典型的な「特別な値」を受け取ることは可能か?
定義域は不必要に広すぎてはいないか?また、不必要に狭すぎてはいないか?
定義域内に「穴」となる値は存在しないか?
定義域外の値が渡された場合は例外となるか?何らかのデフォルトの挙動を示すか?
定義域の範囲が、呼び出し側に何らかの常識を強制するような記述にはなっていないか?
引数の型は適切か?より適切な型を定義する必要はないか?
受け取ったオブジェクトの状態は変更されるか?

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第3章、048項、3段落)

観点一覧:返却

コレクション返却の場合、ソートの有無は記載すべきかなと思います。
データベースから取得するレコードが複数ある場合、ソートしていない場合は選択順序が一定にならない可能性があります。


定義域のすべての範囲に対して、適切な返却値が定義されているか?
定義域外の値を受け取った場合に、何らかの値を返すようなことはないか?
特定の状況下では、特異な値を返すようにはなっていないか?
メソッドは無分別にnullを返していないか?
返された値を、呼び出し側でチェックする必要はないか?
特定の値に対して、特別な意味を与えていないか?
booleanを返す場合、メソッド名から結果を類推できるか?
オブジェクトを返す場合、呼び出し側はそのオブジェクトを変更可能か?変更しても問題はないか?
配列やコレクションを返す場合、内容は特定の順序でソートされているか?

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第3章、048項、3段落)

観点一覧:例外

発生状況等は記載したほうが良いです。
特にプロジェクト特有の例外の場合は、特定のシチュエーションで発生する事を想定しているはずです。


例外が発生する状況がわかるようになっているか?
その例外の発生を回避するための情報は与えられているか?
不要な非検査例外を挙げていないか?
非検査例外のうち、呼び出し側で対応可能なものは挙げられているか?

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第3章、049項、2段落)

フィールド

存在意義

javaだったらそんなに気にしなくてもOK

観点一覧


その定数が表現する概念を明確にする
その定数の実際の値は、極力表に出さない
その定数が使われる具体的なメソッド名は、決して表に出さない。

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第3章、071項、4段落)

アノテーション

存在意義

基本的には観点と同義。
命名で役割が分かるようになっていると良い。

観点一覧


そのアノテーションは、対象となったプログラム要素(メソッド、クラス、引数、コンストラクタ……等)にどのような意味をもたらすか
そのアノテーションを読み取るツールは、どのような振る舞いをするべきか

引用元:佐藤 竜一(2009年06月29日発行 第1版)
「エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方」(第3章、071項、4段落)

列挙型

存在意義

enumは、概念さえ表現できればOK
列挙定数がすべてpublicになるので、対象のドキュメンテーションは必要
メソッドや振る舞いを実装する場合は、上記の観点と同様に留意する。

観点一覧

クラスメソッドと同一観点。

例外

存在意義

観点一覧と同義。

観点一覧

何を通知する例外か?
どのようなときに発生するかが記載されているか?

シリアライズ

別途追記予定

機能編

ボリュームが増えそうなので、別記事にまとめる予定

シェアする

  • このエントリーをはてなブックマークに追加

フォローする