Schreiben von Dokumentation für gut verstandene Methoden wie Equals in Java

Ist es eine gute Praxis, Kommentare für weithin bekannte Methoden wie equals, compareTo usw. zu schreiben?

Betrachten Sie den folgenden Code.

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

               //code for equals

     }   

Mein Unternehmen möchte unbedingt Kommentare wie die oben genannten eingeben. Ist der oben genannte Javadoc-Kommentar erforderlich? Ist es nicht offensichtlich und gut verstanden, was die Equals-Methode und die Likes (compare, compareTo) usw. bewirken?

Was sind deine Vorschläge?

JavaDoc unterstützt bereits das Erben von Kommentaren . Laut Dokumentation erben "Konstruktoren, Felder und verschachtelte Klassen keine Dokumentkommentare", sondern Methoden wie equals()will. Da die ObjectKlasse eine gut dokumentierte hat equals()Methode, sollten Sie nur in der Lage sein , diese Dokumentation ohne ein Problem zu erben.

Die Dokumentation für die Methode muss von irgendwoher stammen, damit in Ihrer IDE und in der generierten Webdokumentation darauf zugegriffen werden kann. Es ist nicht erforderlich, genaue und umfassende Kommentare, die in einer Oberklasse vorhanden sind, explizit neu zu schreiben, und ich würde argumentieren, dass die Codedateien unübersichtlich sind.

Wenn dies eine Unternehmensrichtlinie ist, haben Sie zwei Möglichkeiten. Sie können mühelos mitmachen und den zusätzlichen Aufwand für das Schreiben und Verwalten von Dokumentationen bewältigen (häufig unter Verstoß gegen das DRY-Prinzip, das auch auf Dokumente und Code angewendet werden kann). Die andere Möglichkeit wäre, nach Unternehmensrichtlinien zu suchen - zu erklären, warum diese Richtlinien keine gute Idee sind und welche Vorteile eine Änderung bietet (in Bezug auf Zeit, Geld, Aufwand, Qualität - Dinge, die das Management versteht).

In meinem Team verwenden wir normalerweise die @inheritDocAnmerkung für equals()und hashcode()aber ich wünschte, wir hätten es nicht getan.

Für diese beiden Methoden muss ich immer die Implementierung betrachten. Da Sie eine Methode überschreiben, bedeutet dies, dass Sie möchten, dass sie etwas anderes ausführt. Ich denke, das verdient eine eigene Dokumentation.

Es ist gut, zumindest zu dokumentieren, welche Attribute an der Methode beteiligt sind und vielleicht sogar warum.

Denken Sie daran, dass Kommentare Entwicklern aller Art helfen, wenn sie korrekt sind.

Das Problem ist, dass sie manchmal unvollständig und nicht genau sind.

Um ehrlich zu sein, kann das Vergleichen von 2 Objekten schwierig sein (z. B. das Vergleichen von 2 Rechnungsobjekten). Auch Ihre Methode kann sich mit der Zeit weiterentwickeln und muss dann kommentiert werden.

Es ist eine gute Sache, das Methodenziel, die Regeln usw. in einem "nützlichen und aussagekräftigen" Kommentar zu zeigen.

Es ist äußerst schlecht, Code mit leeren Kommentaren wie:

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

Das sagt nichts Nützliches aus. Schlimmer noch, es ist sowohl in Stil als auch in Grammatik schlecht:

1. Kommentare sollten niemals mit "Diese Methode" oder "Diese Klasse" oder "Dies" beginnen. Der Kommentar ist einer Methode oder Klasse anhand seines Speicherorts in der Quelldatei zugeordnet.

2. "das Objekt" sollte "ein Objekt" lesen

3. "Vergleicht die Gleichheit" ist nur dann sinnvoll, wenn das eine Objekt mehr "Gleichheit" als das andere haben kann. Diese Funktion vergleicht nicht "Gleichheit"; Es vergleicht Objekte, um ihre Gleichheit miteinander zu bestimmen.

Stattdessen sollte der Kommentar angeben, wann die beiden Objekte als gleich angesehen werden. Hier würde ich die Methodenbeschreibung komplett weglassen und nur den Rückgabewert dokumentieren, zum Beispiel:

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;
  }
...
}

Generierte Kommentare für triviale Get / Set-Methoden sind die schlechtesten von allen.

Unser Codierungsstandard schreibt vor, dass beim Überschreiben einer Methode keine Dokumentation erforderlich ist, es sei denn, beim Überschreiben ist die Dokumentation in der übergeordneten Klasse oder Schnittstelle für die Unter- oder Implementierungsklasse nicht mehr genau und umfassend.

Für Gleichgestellte möchten wir möglicherweise beachten, dass der Vergleich nur mit einem Primärschlüssel durchgeführt wird, wenn eine datenbankgestützte Entität verglichen wird, da dies nicht vollständig mit der Dokumentation für übereinstimmt Object.equals().

Meiner Meinung nach, und ich denke, dass dies kontrovers sein kann, sollten Sie im Kommentar angeben, in welcher Klasse Sie die Klasse überschrieben haben. Dann, sechs Monate später, wenn Sie sich fragen, ob es implementiert ist oder nicht, können Sie sehen, ohne die Klasse zu öffnen.

Da Sie wissen, dass diese Methoden üblich sind und die meisten Entwickler wissen, wofür sie gedacht sind, müssen Sie dort keine Kommentare abgeben. Kommentare sind auf lange Sicht nicht so zuverlässig, da diese möglicherweise nicht aktualisiert werden, wenn die Implementierung aktualisiert wird, und Verwirrung stiften können. Daher ist es immer besser, Ihren Code lesbar zu machen, da Sie dem meistens vertrauen können.

Darüber hinaus würde ich sagen, dass wenn der Code, den Sie erstellen / bearbeiten, nicht für eine öffentliche API bestimmt ist, Sie die Javadocs für gängige Methoden einfach weglassen, da diese nur Unordnung und Rauschen verursachen.