javadoc - Java ドキュメントのプライベート メンバー変数

Question

ゲッター/セッターが使用するプライベート メンバー変数の説明を、対応するゲッターとセッターを説明する javadocs に指定する必要があるのはなぜですか。

Answer 1

次のようなプライベート変数の説明:

/**
 * the name of this object.
 */
private String name;

... ゲッターとセッターの説明を含めないでください。この変数のプロパティ、不変条件 ( null であってはならないなど) などを含める必要があります。

---

編集：ああ、私はあなたの質問を読み違えました。ゲッター/セッターの説明に変数の説明を含める必要がある理由を尋ねましたが、その逆ではありません。

それらはすべきではありません-そのような変数が存在する必要さえありません。ゲッターとセッターは、このオブジェクトの抽象プロパティの変更 (または取得) を含む可能性のある効果を記述する必要があります。このプロパティがプライベート変数によって実装されていることは関係ありません。

Answer 2

JavaDocsの目的は、開発者がクラスの使用方法を理解できるように、コードのパブリックAPIを文書化することです。目的は、コードの内部動作を公開することではありません。プライベートメンバーをドキュメント化すると、APIドキュメントが読みにくくなります。

プライベートメンバーの意味は、あなたのコードを読んだり維持したりする人だけが興味を持っています。それらの目的は、明確で明確な命名とコードの一般的な優雅さによって伝えられる必要があります。理想的には、コメントすら必要ないはずです。