Javaのequalsなどのよく理解されたメソッドのドキュメントを書く

equals、compareToなどの広く知られたメソッドにコメントを書くことは良い習慣ですか？

以下のコードを検討してください。

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

私の会社は、上記のようなコメントを入力することに激怒しています。上記のJavadocコメントは必要ですか？equalsメソッドなど（compare、compareTo）などが何をするのかが明確でよく理解されていませんか？

あなたの提案は何ですか？

JavaDocはすでにコメントの継承をサポートしています。ドキュメントによると、「コンストラクタ、フィールド、ネストされたクラスはドキュメントコメントを継承しません」が、そのようなメソッドは継承しequals()ます。以来Objectクラスは十分に文書があるequals()方法を、あなただけの問題でなくても、そのドキュメントを継承することができるはずです。

メソッドのドキュメントは、IDEおよび生成されたWebドキュメントからアクセスできるように、どこかから取得する必要があります。スーパークラスに存在する正確で包括的なコメントを明示的に書き換える必要はなく、コードファイルが乱雑であると私は主張します。

これが企業ポリシーの場合、2つのオプションがあります。それに合わせて、ドキュメントを作成して保守するという余分な労力に対処できます（多くの場合、DRYの原則に違反します。これは、ドキュメントだけでなくコードにも適用できます）。もう1つの選択肢は、会社のポリシーを求めることです。このポリシーが適切ではない理由と、ポリシーを変更するメリット（時間、お金、労力、品質、経営陣が理解すること）を説明してください。

私のチームでは、通常使用@inheritDocのための注釈をequals()してhashcode()ますが、私たちはしませんでした望みます。

これらの2つの方法については、常に実装を確認する必要があります。メソッドをオーバーライドしているので、別のことをしたいということです。これは独自のドキュメントに値すると思います。

少なくともメソッドに参加している属性と、それがなぜそうなのかを記録しておくとよいでしょう。

コメントが正しい場合、コメントはあらゆる種類の開発者に役立つことを覚えておいてください。

問題は、それらが時々不完全で正確でないことです。

正直に言うと、2つのオブジェクトを比較するのは難しいかもしれません（たとえば、2つの請求書オブジェクトを比較するなど）。また、メソッドは時間とともに進化する可能性があり、コメントを付ける必要があります。

メソッドの目的、ルールなどを「有用で意味のある」コメントで示すのは良いことです。

次のような空っぽなコメントでコードをポイ捨てすることは非常に悪い習慣です：

/**
 * This method compares the equality of the current object with the object of same type...
 */

これは何の役にも立ちません。さらに悪いことに、スタイルも文法も貧弱です。

1. コメントは、「このメソッド」、「このクラス」、「これ」のいずれでも開始してはなりません。コメントは、ソースファイル内の場所によってメソッドまたはクラスに関連付けられます。

2. 「オブジェクト」は「オブジェクト」と読むべきです

3. 「同等性の比較」は、あるオブジェクトが別のオブジェクトよりも「同等性」を高くできる場合にのみ意味があります。この関数は「同等」を比較しません。オブジェクトを比較して、それらが互いに等しいかどうかを判断します。

代わりに、コメントは2つのオブジェクトが等しいと見なされる場合を示す必要があります。ここでは、メソッドの説明を完全に省略し、戻り値のみを文書化します。次に例を示します。

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

簡単なget / setメソッドに対して生成されたコメントは、すべての最悪です。

私たちのコーディング標準では、メソッドをオーバーライドするときに、親クラスまたはインターフェースのドキュメントがサブクラスまたは実装クラスに対して正確で包括的でない場合を除いて、メソッドをドキュメント化する必要がないことを規定しています。

イコールの場合、データベースに基づくエンティティを比較する場合、比較は主キーでのみ行われることに注意したいかもしれませんObject.equals()。

私の意見では、これは物議を醸すかもしれないと思うので、コメントでクラスをオーバーライドしたクラスを示す必要があります。その後、実装されているかどうかを疑問に思った6か月後、クラスを開かなくても確認できるようになります。

それらのメソッドは一般的であり、ほとんどの開発者はその方法が何であるかを知っているので（IMO）、そこにコメントを付ける必要はありません。実装が更新されたときにコメントが更新されず、混乱を招く可能性があるため、コメントは長期的にはそれほど信頼できません。そのため、コードを読みやすくすることは常に信頼できる方法です。

さらに、作成または編集しているコードがパブリックAPI向けでない場合は、一般的なメソッドのjavadocを除外してください。これらは混乱とノイズを追加するだけです。