Sollten Javadoc-Kommentare zur Implementierung hinzugefügt werden?

Ist es richtig, Javadoc-Kommentare in die Benutzeroberfläche und Nicht-Javadoc-Kommentare in die Implementierung einzufügen?

Die meisten IDEs generieren Nicht-JavaDoc-Kommentare für Implementierungen, wenn Sie automatisch Kommentare generieren. Sollte die konkrete Methode nicht die Beschreibung haben?

Bei Methoden, die nur implementiert sind (keine Überschreibungen), warum nicht, insbesondere wenn sie öffentlich sind.

Wenn Sie eine übergeordnete Situation haben und Text replizieren möchten, dann definitiv nicht. Die Replikation ist ein todsicherer Weg, um Diskrepanzen zu verursachen. Infolgedessen haben Benutzer ein anderes Verständnis Ihrer Methode, je nachdem, ob sie die Methode im Supertyp oder im Subtyp untersuchen. @inheritDocDokumentation verwenden oder nicht bereitstellen - Die IDEs verwenden den niedrigsten verfügbaren Text, um ihn in ihrer Javadoc-Ansicht zu verwenden.

Abgesehen davon, wenn Ihre übergeordnete Version der Dokumentation des Supertyps etwas hinzufügt, könnten Sie in eine Welt voller Probleme geraten. Ich habe dieses Problem während meiner Promotion untersucht und festgestellt, dass die Leute im Allgemeinen nie über die zusätzlichen Informationen in der überschreibenden Version informiert werden, wenn sie über einen Supertyp aufrufen.

Die Behebung dieses Problems war eines der Hauptmerkmale des von mir erstellten Prototyp-Tools. Immer wenn Sie eine Methode aufriefen, wurde angezeigt, ob das Ziel oder potenzielle übergeordnete Ziele wichtige Informationen enthielten (z. B. ein widersprüchliches Verhalten). Wenn Sie beispielsweise put on a map aufrufen, wurden Sie daran erinnert, dass Ihre Elemente vergleichbar sein müssen, wenn Ihre Implementierung eine TreeMap ist.

Sowohl die Implementierung als auch die Schnittstelle sollten über Javadoc verfügen. Mit einigen Tools können Sie die Dokumentation der Schnittstelle mit dem Schlüsselwort @inheritDoc erben.

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

Etwas gute Praxis ist zu setzen

/**
 * {@inheritDoc}
 */

als Javadoc der Implementierung (es sei denn, es gibt etwas zu erklären über die Details der Implementierung).

Wenn Sie eine Methode überschreiben, halten Sie sich im Allgemeinen an den in der Basisklasse / Schnittstelle definierten Vertrag, sodass Sie das ursprüngliche Javadoc ohnehin nicht ändern möchten. Daher ist die Verwendung @inheritDocoder @seedas in anderen Antworten erwähnte Tag nicht erforderlich und dient tatsächlich nur als Rauschen im Code. Alle sinnvollen Werkzeuge erben die Methode javadoc von der hier angegebenen Oberklasse oder Schnittstelle :

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

Die Tatsache, dass einige Tools (ich sehe Sie an, Eclipse!) Diese standardmäßig beim Überschreiben einer Methode generieren, ist nur ein trauriger Zustand, rechtfertigt jedoch nicht, Ihren Code mit nutzlosem Rauschen zu überladen.

Es kann natürlich den umgekehrten Fall geben, wenn Sie der überschreibenden Methode tatsächlich einen Kommentar hinzufügen möchten (normalerweise einige zusätzliche Implementierungsdetails oder eine Verschärfung des Vertrags). Aber in diesem Fall möchten Sie so etwas fast nie tun:

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

Warum? Weil der geerbte Kommentar möglicherweise sehr lang sein kann. Wer wird in diesem Fall den zusätzlichen Satz am Ende der 3 langen Absätze bemerken? Schreiben Sie stattdessen einfach Ihren eigenen Kommentar auf und das ist alles. Alle die javadoc - Tools zeigen immer eine Art von Angegebene von Link, den Sie klicken können , die Basisklasse Kommentar zu lesen. Es macht keinen Sinn, sie zu mischen.

@see Erzeugt einen Link zur Beschreibung in der Benutzeroberfläche. Aber ich denke, es ist gut, auch einige Details zur Implementierung hinzuzufügen.

Sjoerd sagt zu Recht, dass sowohl die Schnittstelle als auch die Implementierung JavaDoc haben sollten. Die Schnittstelle JavaDoc sollte den Vertrag der Methode definieren - was die Methode tun soll, welche Eingaben sie benötigt, welche Werte sie zurückgeben soll und was sie im Fehlerfall tun soll.

In der Implementierungsdokumentation sollten Erweiterungen oder Einschränkungen des Vertrags sowie entsprechende Details der Implementierung, insbesondere die Leistung, aufgeführt sein.

Für das generierte Javadoc ist es ja wichtig. Wenn Sie Verweise auf eine konkrete Implementierung nur über die Schnittstelle deklarieren, ist dies nicht der Fall, da die Methoden der Schnittstelle von der IDE abgerufen werden.