Sollten Implementierungsmethoden JavaDoc-Kommentar haben, wenn die Schnittstelle, die sie implementieren, JavaDoc-Kommentar hat

Question

Angenommen, ich habe eine Schnittstelle wie folgt.

public interface MyInterface{ 

/** 
* This method prints hello 
*/ 
    void sayHello(); 

    /** 
    * This method prints goodbye 
    */ 
    void sayGoodBye(); 
} 

Eine konkrete Klasse implementiert diese Methoden. Nun müssen die Methoden in der konkreten Klasse die Javadocs zusätzlich zu ihrer Methodendefinition definieren? Ich sehe, dass einige Leute die gleiche Javadoc-Definition in die implementierten Methoden der konkreten Klasse kopieren. Ich sehe das nicht als eine gute Übung, denn wenn wir die Definition des Dokuments ändern müssen, müssen wir es an mehreren Stellen ändern.

Was ist die Standardpraxis dafür?

Answer 1

Sie können {@inheritDoc} verwenden, um die Dokumentation der Schnittstelle zu übernehmen, und nur zusätzliche Kommentare hinzufügen, wenn Sie sie für relevant und relevant halten, zusätzliche Informationen für die spezifische Implementierung.

Verwenden Sie @inheritDoc nur dann, wenn Sie der ursprünglichen Oberklasse/Schnittstellendokumentation hinzufügen möchten. Wenn Sie nur eine Kopie wünschen, wird Javadoc dafür sorgen. Es wird sehen, dass die Superklassen-Dokumentation für die überschriebene Methode der Unterklasse gilt, da die Unterklasse keine zusätzliche Dokumentation zur Verfügung stellt.

{@inheritDoc} - Vererbt (Kopien) Dokumentation von der "nächsten" vererbbaren Klasse oder implementierbaren Schnittstelle in den aktuellen Dok-Kommentar an der Position dieses Tags. Auf diese Weise können Sie allgemeinere Kommentare in der Vererbungsstruktur schreiben und den kopierten Text umschreiben.

http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc

Answer 2

tun Nun sind die Methoden in der konkreten Klasse muss auch die javadocs auf ihrer Methodendefinition definieren?

Nein. Es ist bereits angegeben. Die konkreten Methoden sollten genau das tun, was die Schnittstelle Javadoc sagt und sonst nichts.

Ich sehe, dass einige Leute nur die gleiche Javadoc-Definition in die implementierten Methoden der konkreten Klasse kopieren. Ich sehe das nicht als eine gute Übung, denn wenn wir die Definition des Dokuments ändern müssen, müssen wir es an mehreren Stellen ändern.

Sie haben Recht. Sie sollten das nicht tun.

Sie sollten nicht @inheritDoc entweder verwenden, außer in dem sehr seltenen Fall, wo die konkrete Methode mehr Beschreibung benötigt, als bereits in der Schnittstelle Javadoc.Die meiste Zeit sollten Sie keine Javadoc bieten überhaupt, nicht einmal:

/** 
* 
*/ 

Answer 3

Sie sollte Kommentar für die konkrete Umsetzung zur Verfügung stellen, wenn

• der Kommentar für die Schnittstelle so allgemein ist es tut die konkrete Umsetzung nicht ausreichend spezifizieren
• die konkrete Umsetzung entspannt alle Voraussetzungen der Schnittstelle
• die konkrete Umsetzung hat strenger (enger) post co Bedingungen als die Schnittstelle.