web-dev-qa-db-ja.com

Javadocコメントを実装に追加する必要がありますか？

インターフェイスにJavadocコメントを追加し、実装に非Javadocコメントを追加するのは正しい習慣ですか？

ほとんどのIDEは、コメントを自動生成すると、実装用の非JavaDocコメントを生成します。具体的なメソッドには説明がありませんか？

javainterfacecommentsjavadoc
99
Vaishak Suresh

実装のみのメソッド（オーバーライドではない）の場合、特にパブリックである場合は、なぜそうなのかを確認してください。

優先する状況があり、テキストを複製する場合は、間違いなくそうです。レプリケーションは、矛盾を引き起こす確実な方法です。その結果、ユーザーはメソッドをスーパータイプで検査するかサブタイプで検査するかによって、メソッドの理解が異なります。つかいます @inheritDocまたはドキュメントを提供しない-IDEは、Javadocビューで使用できる最も低いテキストを使用します。

余談ですが、オーバーライドバージョンがスーパータイプのドキュメントに何かを追加すると、問題が発生する可能性があります。私は博士課程でこの問題を研究しましたが、一般に、スーパータイプを介して呼び出している場合、オーバーライドバージョンの追加情報に気付かないことがわかりました。

この問題に対処することは、私が構築したプロトタイプツールの主要な機能の1つでした-メソッドを呼び出すたびに、そのターゲットまたは潜在的なオーバーライドターゲットに重要な情報（競合する動作など）が含まれているかどうかがわかります。たとえば、マップにputを呼び出すとき、実装がTreeMapである場合、要素を比較する必要があることを思い出しました。

59
Uri

実装とインターフェースの両方にjavadocが必要です。一部のツールでは、@ inheritDocキーワードを使用してインターフェイスのドキュメントを継承できます。

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }
24
Sjoerd

やや良い習慣は置くことです

/**
 * {@inheritDoc}
 */

実装のjavadocとして（実装の詳細について説明する特別なものがない限り）。

20
Vanya

一般に、メソッドをオーバーライドするときは、基本クラス/インターフェースで定義されたコントラクトに従うため、元のjavadocを変更する必要はありません。したがって、他の回答で言及されている@inheritDocまたは@seeタグの使用は不要であり、実際にはコード内のノイズとしてのみ機能します。すべての賢明なツールは、指定されたスーパークラスまたはインターフェースからメソッドjavadocを継承します here ：

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

メソッドをオーバーライドするときにデフォルトでこれらのツールを生成する一部のツール（Eclipse！.

もちろん、実際にオーバーライドメソッドにコメントを追加したい場合（通常、追加の実装の詳細を追加したり、契約を少し厳しくしたりする場合）、反対の場合があります。しかし、この場合、次のようなことはほとんどしたくないでしょう。

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

どうして？継承されたコメントは非常に長くなる可能性があるためです。このような場合、3つの長い段落の終わりに余分な文が表示されるのは誰ですか??代わりに、あなた自身のコメントの一部を書き留めてください、それがすべてです。すべてのjavadocツールは、常に何らかの種類ので指定されたリンクを表示します。このリンクをクリックすると、基本クラスのコメントを読むことができます。それらを混ぜても意味がありません。

16
Natix

@seeインターフェイスの説明へのリンクを生成します。しかし、実装に関する詳細を追加することも良いと思います。

6
redben

Sjoerdは、インターフェイスと実装の両方にJavaDocが必要であると正しく述べています。インターフェースJavaDocは、メソッドのコントラクト（メソッドが行うべきこと、メソッドが取る入力、返す値、エラーの場合に行うべきこと）を定義する必要があります。

実装ドキュメントには、契約の拡張または制限、および実装の適切な詳細、特にパフォーマンスを記載する必要があります。

4
DJClayworth

生成されたjavadocのために、はい重要です。インターフェイスのみを使用して具体的な実装への参照を宣言する場合、インターフェイスのメソッドはIDEによって取得されるため、それは宣言しません。

0
Boris Pavlović