Java Kommentar für Getter und Setter-Methode

Question

meine Frage ist, sollte ich einen Kommentar wie folgt vor:

/** 
    * Getter for {@link #auto_key} 
    * @return {@link #auto_key} 
    */ 
    public String getAuto_key() { 
     return auto_key; 
    } 
    /** 
    * Setter for {@link #auto_key} 
    * @param auto_key the {@link #auto_key} to set 
    */ 
    public void setAuto_key(String auto_key) { 
     this.auto_key = auto_key; 
    } 

im Grunde möchte ich fragen, mit {} @link in Kommentar für Getter und Setter-Methode ist richtig? Oder sollte ich einen normalen Kommentar verwenden, ohne {@link} zu verwenden? und auf diese Weise ist ein Java-Standard oder nicht?

Answer 1

Angelegenheit der Konvention. Weicht Organisation von Organisation ab. Zuvor wurden wir gebeten, Getters und Setter nicht zu kommentieren, solange es offensichtlich ist, was es tut. Was ist das gleiche wie Kommentare ohne {@link}.

Zur Zeit fügen wir {@link} hinzu, da bereits früher geschriebene Codes diese Konvention haben.

Answer 2

Eigentlich habe ich absichtlich keine Javadoc Getters und Setter, weil Sie keinen Wert dadurch hinzufügen - sie sind was sie sind ... Accessor-Methoden. In der Tat würden Sie eine Art Code Bloat erstellen, indem Sie ihnen javadoc hinzufügen.

Ich habe nur Javadoc auf Non-Getter/Setter gesetzt.

Answer 3

Wenn Sie in Ihrer Dokumentation auf #auto_key unter Verwendung der {@link} verweisen können, bedeutet dies, dass die Variable öffentlich zugänglich ist (andernfalls würde die Verknüpfung im Javadoc nicht aufgelöst werden). Das bedeutet, dass Getter und Setter redundant sind.

Ich würde dringend empfehlen, Ihre auto_key Feld privat und halten Sie die Getter und Setter. Passen Sie dann den Namen von Getter und Setter an die Java-Konventionen an (autoKey, setAutoKey, getAutoKey). Und in Betracht ziehen, PropertyChangeEvent s zu feuern, wenn die autoKey geändert wird (wie eine Getter/Setter-Kombination typischerweise vorschlägt - siehe JavaBeans).

Wie für Ihre Dokumentation: Es fügt nichts Neues zu dem, was der Name der Methode bereits vorschlägt. Also würde ich es entfernen, oder fügen Sie einige zusätzliche Dokumentation auf, was die autoKey genau tut (was mir aus dem Schnipsel nicht klar ist), ob es auf null eingestellt werden kann, ....

Answer 4

1. würde ich vorschlagen, für Ihr Set Stand-alone-Dokumentation zu erzeugen/Methoden erhalten, während immer noch {@link} verwenden, das ist beides zu tun. Wenn das Feld zugänglich ist, können die Leute auf diese Weise zu ihrer Dokumentation gelangen. Wenn es danach aufgrund eines Refactorings wieder privat wird, werden Sie nicht mit einer Menge unvollständiger Javadocs enden, die ebenfalls modifiziert werden müssen.

2. Während Dokumentation für Setter/Getter-Methoden wie Code aufblasen erscheinen mag, würde ich es immer noch für ein paar Gründe, empfehlen die Erstellung:

   • Es gibt Ihnen eine Standard-Standort wichtige Informationen zu erwähnen, wie Setze Argumente, die nicht null oder Getter sein sollten, die in einer bestimmten Implementierung einer Schnittstelle beklagenswert ineffizient sind.

   • Es geht nicht davon aus, dass der Leser automatisch weiß, was das Hintergrundfeld tut. Sicher, setLength() kann in einigen Kontexten beschreibend genug sein, aber was genau macht setLimit()?

   • Es geht nicht davon aus, dass ein Hintergrundfeld ist, oder dass die Get/Set-Methoden nur genau das in einer bestimmten Implementierung tun. Es ist eine unglückliche Realität, dass, wenn das Refactoring durch Kompatibilitätsprobleme eingeschränkt wird, verschiedene Artefakte zurückbleiben. Z.B. setLimit() könnte an setSizeLimit() delegieren, was etwas zu beachten ist.

   • Es entfernt jede Zweideutigkeit. Was Sie für gesunden Menschenverstand halten, ist vielleicht nicht für alle Menschen geradlinig. Ohne Dokumentation werden verschiedene Annahmen getroffen, die wahr sein können oder auch nicht. Zum Beispiel, in einer Listenimplementierung, setzt setLength(0) auch alle enthaltenen Referenzen auf null oder nicht?

   • Vor allem erlaubt es der Javadoc-Politik, auf ein einfaches "Dokument alles überall" herunterzukochen. Eine Politik mit verschiedenen Ausnahmen führt jedoch zwangsläufig zu Lockerheit und Code, der schließlich undokumentiert bleibt.

Answer 5

Sie sollten noch keine Kommentare zu beschreiben Getter oder Setter setzen, es sei denn, die Methode, wie man aussieht, aber ein anderes Verhalten verkapselt.