web-dev-qa-db-ja.com

Javadoc @returnタグのコメントの複製が必要ですか？

インスタンスの状態を変更しない関数の場合、メソッドのjavadocコメントは、Java-APIの@ return-tagのコメントと同じか、非常によく似ています。

boolean Collection.isEmpty（）

  • このコレクションに要素が含まれていない場合はtrueを返します。
  • 戻り値：このコレクションに要素が含まれていない場合はtrue

今、私は同じ問題を抱えているgetExpression（）のような多くの単純なメソッドのjavadocを書いています。 APIのように行うべきですか、それとも省くべきですか？

javajavadoc
31
Konrad Höffner

Oracleの推奨から Javadocツールのドキュメントコメントの書き方 ：

@return（リファレンスページ）

Voidを返すメソッドとコンストラクターの@returnを省略します。 その内容がメソッドの説明と完全に冗長であっても、他のすべてのメソッドにそれを含めます。明示的な@returnタグを使用すると、誰かが戻り値をすばやく見つけやすくなります。可能な限り、特別な場合の戻り値を指定します（範囲外の引数が指定されたときに返される値を指定するなど）。

20
Alex Stybaev

あなた（私のような）が本当にDRYに違反したくない場合、これはjavadoc refの最も重要な行の1つです。

タグセクションのみを持ち、主要な説明を持たないコメントを含めることができます。

（@see http://docs.Oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#tagsection ）

したがって、次のようにjavadocを記述する単純なメソッドに対して完全に有効です（そして機能します）。

/**
* @return the name of the object
*/
public String getName();

そのため、次のように書くこともできます。

/**
* @return the n-th element of the object
*
* @param n index of element to get
*/
public String get( int n );

DRYに違反する長い形式ほど、ソースで読みやすく、保守性が向上します（お互いを少し知った後）。

21
Scheintod