Sollten Javadoc-Kommentare zur Implementierung hinzugefügt werden?

109

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?

Vaishak Suresh
quelle

Antworten:

67

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.

Uri
quelle
1
Wissen Sie nicht bereits, dass Elemente bei Verwendung einer TreeMap vergleichbar sein müssen? Eine Implementierung sollte auch kein widersprüchliches Verhalten implementieren.
Jimmy T.
1
Ich denke, dies sollte die richtige Antwort sein stackoverflow.com/a/39981265/419516
user219882
26

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)
{ ... }
Sjoerd
quelle
5
Was genau sind "einige Werkzeuge"? Funktioniert es sofort oder ist es an bestimmte Plugins gebunden?
Jediz
Ich weiß, dass Eclipse verwendet {@inheritDoc}und es funktioniert nur, wenn Sie nicht die Annotation @Overridezuerst haben
ksnortum
24

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).

Wanja
quelle
2
Der Punkt einer Schnittstelle ist, dass die Methode auf mehrere Arten implementiert werden kann. Wenn ich nur die Kommentare erben möchte, was bringt es dann, wenn der Kommentar in der Implementierung enthalten ist?
Vaishak Suresh
16
Ich verwende das obige Tag und füge dann alle zusätzlichen erforderlichen Unterlagen unter das Tag ein.
Ben Page
17

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.

Natix
quelle
6

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

redben
quelle
6
IMO, das @seeVerknüpfen mit Schnittstellenmethoden verwendet, ist eine gute Praxis und in den meisten Fällen ausreichend. Wenn Sie Javadoc von der Schnittstellenmethode in die konkrete Implementierung kopieren, duplizieren Sie nur Informationen und diese können schnell inkonsistent werden. Zusätzliche Informationen zur Implementierung sollten jedoch zu javadoc hinzugefügt werden.
Piotr
1
In dem zusätzlichen Dokument geht es nicht darum, das Dokument von der Benutzeroberfläche zu kopieren, sondern nur zu erklären, wie Sie die Methode und ähnliches implementieren. Mit einem Schnittstellendokument erklären Sie, was die Ergebnisse / Ziele (Anwendungsstatus oder Methodenrückgabe) sind, während es in Ihrer Implementierung hilfreich sein kann, zu erklären, wie Sie diese Ziele erreichen.
Redben
4

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.

DJClayworth
quelle
0

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.

Boris Pavlović
quelle