☰

Javadoc @return タグのコメントの重複は必要ですか? 質問する

tag-icon • tag-icon java javadoc
Javadoc @return タグのコメントの重複は必要ですか? 質問する

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

ブール型 Collection.isEmpty()

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

現在、getExpression() などの多くの単純なメソッドの javadoc を書いていますが、ここでも同じ問題が発生します。API と同じように行うべきでしょうか、それとも省略すべきでしょうか?

ベストアンサー1

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

メインの説明がなく、タグ セクションのみのコメントを記述することも可能です。

（@見る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 に違反する長い形式としてより保守しやすくなります。

おすすめ記事