JavaDoc-Kommentare Schnittstelle

Habe ich ein interface die Methoden x, y und z. Ich bin kommentieren Sie die Klasse auf diese Weise:

/**
 * 
 * A.java
 * Interface class that has the following methods.
 * 
 * @author MyName
 * @since mm-dd-yyyy
 */

public interface A {

    //method description for x
    void x();

    //method description for y
    void y();

    //method description for z
    void z();
}

Ist es richtig oder sollte ich andere Dinge um die KLASSE KOMMENTARE?

Warum akzeptieren nicht Sie Jon Skeet?

InformationsquelleAutor FranXh | 2012-02-10

  1. 12

    Ja, schreiben Sie die richtige Javadoc-Kommentare für Ihre Schnittstellen zu eindeutig bestimmten die motivation hinter der Schnittstelle und was der Vertrag ist für beide Anrufer und implementors.

    Werfen Sie einen Blick auf einige der Schnittstellen der JDK-code für Beispiele, wie java.util.Liste

    InformationsquelleAutor Peter Liljenberg

  2. 35

    Nein, du hast nicht angegeben JavaDoc-Kommentare für die Methoden. Wie ist jemand, der oder die das interface gemeint zu wissen, was die Methoden tun sollen? Sie sollte die ordnungsgemäße Verwendung von JavaDoc-Beschreibungen:

    /**
 * This method fromulgates the wibble-wrangler. It should not be called without
 * first saturating all glashnashers.
 */
void x();

    Beachten Sie, dass im Gegensatz zu den meisten JavaDoc, das darauf abzielt Anrufer, interface-Dokumentation hat zwei Zielgruppen: dem Anrufer und Praktiker. Sie müssen sich darüber im klaren sein, was beide Seiten erwarten können und wie Sie sich Verhalten sollte. Ja, das ist schwer zu tun, gut 🙁

    EDIT: In Bezug auf die top-level-Kommentare:

    • Würde ich persönlich loszuwerden, die @author tag, wie es selten sinnvoll, IMO. (In der Regel auf der Suche in source control ist besser geeignet...)
    • Es sei denn, Sie eigentlich eine sinnvolle Versionierung Politik (nicht nur Daten), würde ich loswerden der @since tag.
    • Es gibt keinen Punkt bei der Angabe der Quell-Datei
    • Eine Beschreibung von "Interface-Klasse hat die folgenden Methoden," ist bedeutungslos und widersprüchlich (wie eine Schnittstelle ist keine Klasse). Wer ' s Lesen der JavaDoc schon in der Lage sein, um die Liste der Methoden. Sie sollten versuchen, um zusätzliche Informationen finden Sie hier.

    Genauso wie für die normale Klasse Dokumentation, interface-Dokumentation sollte hervorgehen, was der Zweck des Typs - seine Rolle in den größeren Plan der Dinge, vielleicht ein Beispiel wie es verwendet werden soll, etc. Blick auf Beispiele in der JDK für allgemein-vernünftigen JavaDoc.

    Ich bin nicht zu Fragen, über die Methoden get Kommentare, ich Frage nach der Klasse commetn. Ich weiß, wie man gängige Methoden, die ich bin nicht sicher über Interface-Klassen nur
    Auch wenn Sie ein Beispiel geben, das es versäumt zu dokumentieren, die Methoden und Fragen, ob Sie das richtige zu tun, was erwarten Sie?
    Ich Frage, ob ich richtig Klasse Kommentar. Ich habe angegeben, dass in meiner Frage
    Tatsächlich, ich hasse es, wenn ich eine Bibliothek in einer version anders, was ist die neueste version dokumentiert auf der Website, und dies ist ohne version-tags, die angibt, ob die Methode gab es schon immer. (Aber das bedeutet natürlich, dass Sie sollte eine Versionsverwaltung Politik wenn Sie schreiben und veröffentlichen einer Bibliothek.) Alternativ, setzen Sie Javadoc für alle - Versionen der Bibliothek auf Ihrer website.
    Ja, wenn du gehst zu tun, Versionierung richtig, dann dokumentieren Sie es - aber gerade dabei, das Datum ist nur selten sinnvoll, IMO... vor allem, wenn Sie fügen Sie Methoden der interface-ohne Feststellung, es...

    InformationsquelleAutor Jon Skeet

Schreibe einen Kommentar