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

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

ほとんどのIDEは、コメントを自動生成すると、実装に対して非JavaDocコメントを生成します。具体的な方法に説明があってはいけませんか？

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

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

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

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

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

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

やや良い習慣は

/**
 * {@inheritDoc}
 */

実装のjavadocとして（実装の詳細について説明する必要がある場合を除いて）。

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

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ツールには常に、特定の種類のSpecified byリンクが表示され、クリックして基本クラスのコメントを読むことができます。それらを混ぜ合わせても意味がありません。

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

Sjoerdは、インターフェースと実装の両方にJavaDocが必要であることを正しく述べています。インターフェースJavaDocは、メソッドの規約を定義する必要があります-メソッドが何をすべきか、どのような入力が必要か、どの値が返すべきか、エラーの場合に何をすべきか。

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

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