Einfache Getter / Setter-Kommentare

124

Welche Konvention verwenden Sie, um Getter und Setter zu kommentieren? Das habe ich mir schon seit einiger Zeit gefragt:

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

Ich finde immer, dass ich für 1a / b und 2a / b genau dasselbe schreibe, so etwas wie 1a) Legt das Gehalt des Mitarbeiters fest, 1b) das Gehalt des Mitarbeiters. Es scheint einfach so überflüssig. Jetzt könnte ich für etwas Komplexeres sehen, dass Sie vielleicht mehr in die (a) Teile schreiben, um den Kontext zu geben, aber für die Mehrheit der Getter / Setter da draußen ist der Wortlaut fast genau der gleiche.

Ich bin nur neugierig, ob es für die einfachen Getter / Setter in Ordnung ist, nur entweder den (a) Teil oder den (b) Teil auszufüllen.

Was denken Sie?

ThaDon
quelle
54
Nebenbei bemerkt, verwenden Sie float niemals für irgendetwas Geld (wie zum Beispiel das Gehalt hier). Siehe z. B. stackoverflow.com/questions/965831/…
Jonik
3
Verwenden Sie stattdessen BigDecimal.
Josep

Antworten:

83

Normalerweise fülle ich nur den Parameterteil für Setter und den @ Rückgabeteil für Getter aus:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

Auf diese Weise werden Javadoc-Überprüfungswerkzeuge (wie die Warnungen von Eclipse) sauber ausgegeben, und es gibt keine Duplikate.

sleske
quelle
Können Sie den Tippfehler beheben? "@return Teil für Setter"
Jonik
1
Es gibt auch einen Tippfehler im Kommentar von Gehalt (). Es ist kein JavaDoc-Kommentar.
Fostah
1
Ich bin damit einverstanden, dass dies der beste Ansatz ist, um Accessoren zu kommentieren.
Fostah
30
Das Hinzufügen von Rauschen zu Ihrem Code, um übermäßig pedantische Warnungen von unseren Tools auszuschalten, fühlt sich für mich falsch an. Wenn es einem Programmierer keinen Mehrwert bringt, besteht die richtige Lösung darin, die Ausführlichkeit der Werkzeuge zu verringern / zu korrigieren und / oder zu vereinfachen, wie wichtig es uns ist, durch Reifen zu springen, damit die Werkzeuge uns belohnen. Analysetools sollen uns helfen und Mühe sparen, nicht sinnlosere Aufgaben für uns schaffen.
Lyle
1
@Lyle Das mag wahr sein, aber ich denke, es gibt fast immer etwas Nützliches, das ein Programmierer sagen kann, das einen Getter / Setter besser beschreibt als nur die Methodensignatur allein. Ja, es gibt Fälle, in denen ein Programmierer faul ist und nur die Methodensignatur im Kommentar wiederholt, aber ich denke, dass es im Allgemeinen ein hilfreiches Verhalten ist, dies zu erzwingen.
Matt Vukas
174

Absolut sinnlos - Sie sind besser dran, ohne dass diese Art von Mist Ihren Code durcheinander bringt:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

Sehr nützlich, wenn dies gerechtfertigt ist:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

Insbesondere die Erklärung, was die Eigenschaft tatsächlich bedeutet, kann in Domänenmodellen von entscheidender Bedeutung sein. Immer wenn ich eine Bohne voller Eigenschaften mit obskuren Namen sehe, die nur Investmentbanker, Biochemiker oder Quantenphysiker verstehen, und die Kommentare erklären, dass die setGobbledygook () -Methode "das Gobbledygook setzt", möchte ich jemanden erwürgen.

Michael Borgwardt
quelle
2
Genau meine Meinung, die schlimmsten sind die domänenspezifischen Modelle, bei denen nur ein Domain-Experte weiß, was zum Teufel die Eigenschaft bedeutet.
ThaDon
7
Auch wenn es nützlich ist, was würden Sie für getFoo () tun. Kopieren Sie denselben Kommentar auch für getFoo ()?
Vinoth Kumar CM
3
@cmv: Offensichtlich würde der "param" Teil nicht kopiert. Ich bin mir nicht sicher, ob der Wert, die Informationen an beide Accessoren anzuhängen, das Duplizieren der Informationen direkt rechtfertigt. Wahrscheinlich ja. Noch besser wäre es, beiden einen Kommentar beizufügen. Ich glaube, dass dies in Project Lombok verfügbar ist.
Michael Borgwardt
@VinothKumar: Vielleicht wäre es besser, einfach die Eigenschaft im Getter (wie in "Foo ist der in der Balkenberechnung verwendete Anpassungsfaktor.") Und die Auswirkungen der Änderung des Werts im Setter (oder ob dies erforderlich ist) zu erklären oder diesen Wert nicht zu initialisieren - im Beispiel der Antwort ist es nicht erforderlich, Foo zu initialisieren, da "es einen Standardwert hat, der vom Baz-Typ abhängt").
Freitass
+1 für "obskure Namen, die nur Investmentbanker, Biochemiker oder Quantenphysiker verstehen"
Jackson,
36

Im Allgemeinen nichts, wenn ich es ändern kann. Getter und Setter sollten selbsterklärend sein.

Ich weiß, das klingt nach einer Nichtantwort, aber ich versuche, meine Zeit zu nutzen, um Dinge zu kommentieren, die einer Erklärung bedürfen.

Eric Wendelin
quelle
5
Eine andere gültige Antwort in dieser Richtung könnte sein: "Entwürfe mit Gettern und
Setzern
2
@Trejkaz: Nicht wahr, da Accessor-Methoden schreibgeschützte oder schreibgeschützte Eigenschaften sowie Polymorphismus (und damit Wrapping, Proxy usw.) zulassen.
Laurent Pireyn
2
Sie können diese Dinge
berücksichtigen
Ich mag und verwende das Builder-Muster auf jeden Fall, aber es gibt so viel Unterstützung für POJOs (z. B. im Ruhezustand), dass Getter und Setter immer noch ihren herausragenden Platz haben, zum Guten oder zum Schlechten. Es ist das Schlimmste an Java, IMHO, und nachdem ich über ein Jahrzehnt lang sich wiederholende JavaDocs geschrieben habe, bin ich bereit, den Rat von @ sleske zu abonnieren.
Michael Scheper
34

Ich würde sagen, Sie müssen sich nur darum kümmern, Getter und Setter zu kommentieren, wenn sie eine Nebenwirkung haben oder eine Vorbedingung außerhalb der Initialisierung erfordern (dh: Beim Abrufen wird ein Element aus einer Datenstruktur entfernt oder um etwas festzulegen, das Sie benötigen zuerst x und y an Ort und Stelle haben). Ansonsten sind die Kommentare hier ziemlich überflüssig.

Bearbeiten: Wenn Sie feststellen, dass Ihr Getter / Setter viele Nebenwirkungen hat, möchten Sie den Getter / Setter möglicherweise so ändern, dass er einen anderen Methodennamen hat (z. B. Push and Pop für einen Stapel) die Kommentare unten]

Gopherkhan
quelle
10
Sie sollten den Namen der Getter mit Nebenwirkungen ändern, um klarer zu werden, da nicht alle Entwickler die Kommentare lesen.
Akf
Das ist in Ordnung - aber das setzt voraus, dass Benutzer Ihrer API wissen, dass sie dokumentiert worden wären , wenn es irgendwelche Nebenwirkungen gegeben hätte !
oxbow_lakes
akf, ich habe genau das nach dem posten gedacht :) Ich denke, ich werde es meiner Antwort hinzufügen.
Gopherkhan
1
Aber wenn Sie keine "dummen" Getter und Setter dokumentieren (das ist auch das, was ich bevorzuge!) - wie können Sie Eclipse-Warnungen bei fehlendem Javadoc loswerden? Ich möchte meinen Arbeitsbereich nicht mit
solchen Warnungen überladen
12

Fragen Sie sich, was die Benutzer sehen sollen, wenn die Kommentare als JavaDocs (über einen Browser) angezeigt werden. Viele Leute sagen, dass Dokumentation nicht notwendig ist, da es offensichtlich ist. Dies gilt nicht, wenn das Feld privat ist (es sei denn, Sie aktivieren JavaDocs explizit für private Felder).

In deinem Fall:

public void setSalary(float s)
public float getSalary()

Es ist nicht klar, in welchem ​​Gehalt ausgedrückt wird. Es sind Cent, Dollar, Pfund, RMB?

Bei der Dokumentation von Setzern / Gettern möchte ich das Was von der Codierung trennen. Beispiel:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

Die erste Zeile gibt an, dass die Höhe zurückgegeben wird. Der Rückgabeparameter dokumentiert, dass die Höhe in Metern angegeben ist.

Steve Kuo
quelle
1
Obwohl ich Ihnen zustimme, denke ich, dass man sicherstellen muss, dass die Funktionskommentare keinen schlecht gewählten, nicht expliziten Funktionsnamen ausmachen.
Karlipoppins
Ich bin ein großer Befürworter von JavaDocs, aber auch ein großer Befürworter von selbstdokumentierendem Code. Zumindest für den Setter würde ich so etwas tun public void setSalary(float aud)(oder realistischer public void setSalary(BigDecimal aud)). Besser noch, die Eigenschaft sollte vom Typ sein abstract class CurrencyAmount, der wiederum die Eigenschaften java.util.Currency currencyund hat java.math.BigDecimal amount. Die meisten Entwickler, mit denen ich zusammengearbeitet habe, sind mit JavaDoc furchtbar faul, aber die Durchsetzung einer solchen API macht dies weniger problematisch.
Michael Scheper
Wenn es sich bei der Einheit um eine SI-Einheit wie Meter / Sekunden handelt, muss weniger dokumentiert werden. Wenn es sich nicht um eine Si-Einheit handelt, muss sie dokumentiert oder besser benannt werden, um die nicht standardmäßige Einheit einzuschließen, z. B. heightFeet
AlexWien
8

Warum enthalten sie nicht einfach ein Referenz-Tag, mit dem Sie den Feldwert und die Referenz von Gettern und Setzern kommentieren können?

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

Damit gilt die Dokumentation sowohl für den Getter und Setter als auch für das Feld (wenn also private Javadocs aktiviert sind).

Steve
quelle
Genau. Und dann wurde mir klar, warum ich das alles überhaupt schreiben sollte. Siehe meine Antwort zu Project Lombok.
Michael Scheper
7

Diese Art von Boilerplate kann mit Project Lombok vermieden werden . Dokumentieren Sie einfach die Feldvariable, auch wenn dies der privateFall ist , und lassen Sie Lombok-Annotationen ordnungsgemäß dokumentierte Getter und Setter generieren.

Allein dieser Vorteil ist für mich die Kosten wert .

Michael Scheper
quelle
4

Ich bin wirklich enttäuscht über die Antworten, die besagen, dass eine umfassende Dokumentation Zeitverschwendung ist. Woher sollen Clients Ihrer API wissen, dass eine aufgerufene Methode setXein Standard-JavaBean-Eigenschaftssetzer ist, sofern Sie dies in der Dokumentation nicht klar angeben ?

Ohne Dokumentation hätte ein Anrufer überhaupt keine Ahnung, ob die Methode irgendwelche Nebenwirkungen hatte, außer indem er die Daumen über die offensichtliche Konvention drückte, die befolgt wird.

Ich bin sicher, dass ich nicht der einzige hier bin, der das Unglück hatte, herauszufinden, auf welche harte Weise eine aufgerufene Methode setXviel mehr kann, als nur eine Eigenschaft festzulegen.

oxbow_lakes
quelle
11
Ohne Dokumentation würde jeder Aufrufer davon ausgehen, dass eine Methode namens setX X setzt. Daraus folgt, dass Sie keine Dokumentation benötigen, wenn setX tatsächlich X setzt, ohne etwas anderes Wichtiges zu tun.
mqp
Das ist großartig! Befolgt diese Firma CrudTech, gegen deren API ich codiere, Ihre Konvention oder folgt sie der eines anderen in diesem Thread? Hmmmm
oxbow_lakes
5
Es macht keinen Sinn, im setPrice-Dokument "setzt den Preis" zu schreiben, wenn die Methode nur den Wert für die Eigenschaft price festlegt, aber wenn sie beispielsweise auch die Eigenschaft totalPrice aktualisiert und die Steuer neu berechnet, sollte ein solches Verhalten offensichtlich dokumentiert werden.
João Marcus
8
Sie scheinen nach der Dokumentation zu fragen, in der steht: "Dies tut, was Sie erwarten." Das ist ein bisschen so, als würde man "Achtung: HEISS" auf eine Tasse Kaffee schreiben. In einer perfekten Welt wäre es nicht nötig, jemals solche Dinge zu sagen.
Kevin Panko
1
Ja - nachdem ich APIs verwendet habe, bei denen Methoden, die als Dinge bezeichnet setXwerden, andere als die erwarteten Nebenwirkungen hatten, kann ich in der Tat mit Zuversicht feststellen, dass dies keine perfekte Welt ist.
oxbow_lakes
4

Wenn es in Getter / Setter keine spezielle Operation gibt, schreibe ich normalerweise:

Mit Javadoc (mit privater Option):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

und / oder

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Mit Doxygen (mit privater Extraktoption):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();
TermWay
quelle
2
Das Problem bei diesem Ansatz ist, dass Javadoc die private Dokumentation nicht standardmäßig generiert! In diesem Fall ist das Referenz-Tag {@see #salary}in der generierten Dokumentation ungültig.
Jarek Przygódzki
1

Das Kommentieren von Accessoren, insbesondere wenn sie nirgendwo Operationen ausführen, ist unnötig und eine Verschwendung von Fingerspitzen.

Wenn jemand, der Ihren Code liest, nicht verstehen kann, dass person.getFirstName()der Vorname einer Person zurückgegeben wird, sollten Sie alles in Ihrer Macht Stehende versuchen, um sie zu entlassen. Wenn es Datenbankmagie ausführt, ein paar Würfel wirft, den Sekretär für Vornamen anruft, um den Vornamen zu erhalten, kann man davon ausgehen, dass es sich um eine nicht triviale Operation handelt, und sie gut dokumentieren.

Wenn Sie andererseits person.getFirstName()den Vornamen einer Person nicht zurückgeben ... nun, gehen wir nicht dorthin, sollen wir?

Henrik Paul
quelle
6
Was ist, wenn getFirstName () null zurückgibt? Wo würde das dokumentiert werden?
Steve Kuo
Wie wäre es mit security.getFinalMaturity ()? Nicht alle Eigenschaftsnamen haben eine sofort verständliche Bedeutung. Möchten Sie entlassen werden, weil Sie nicht wissen, was das bedeutet?
Michael Borgwardt
Was ist, wenn die Methode durch Swizzling implementiert wird? Woher solltest du das wissen, wenn es nicht eindeutig dokumentiert ist? Woher solltest du wissen, dass es sich um einen Standardsetzer handelt, es sei denn, der Arzt sagt, dass dies der Fall ist?
oxbow_lakes
2
get / set sollte meiner Meinung nach für Getter und Setter reserviert sein. Datenbanksuchen sollten den Namen "lookupPerson" oder so haben.
Thorbjørn Ravn Andersen
1

Geben Sie nichts ein, wenn der Feldname den Inhalt ausreichend beschreibt.

Lassen Sie den Code im Allgemeinen selbstständig sein und vermeiden Sie Kommentare, wenn dies überhaupt möglich ist. Dies erfordert möglicherweise ein Refactoring.

BEARBEITEN: Das Obige bezieht sich nur auf Getter und Setter. Ich glaube, alles, was nicht trivial ist, sollte richtig javadociert werden.

Thorbjørn Ravn Andersen
quelle
1
Es gibt einen Unterschied zwischen Kommentieren und Dokumentieren.
Tom Hawtin - Tackline
1
Sehr richtig. Genau deshalb kommentiere ich Getter und Setter nicht. Sie sollten selbsterklärend sein, und das Hinzufügen eines Kommentars zeigt an, dass der Code nicht selbsterklärend ist.
Thorbjørn Ravn Andersen
0

Es ist in Ordnung, den Teil (b) auszufüllen, insbesondere wenn Sie in die Felddeklaration einen Kommentar einfügen, der angibt, worum es in dem Feld geht.

akf
quelle
Nicht gut - die Leute lesen die Feldkommentare nicht. Javadoc generiert standardmäßig nicht einmal die private Dokumentation, und IDEs zeigen Ihnen die Felddokumentation nicht an, wenn Sie bei einem Methodenaufruf eine schnelle Hilfe verwenden.
Trejkaz
Leute lesen die Feldkommentare nicht, es sei denn, sie müssen. Je mehr Informationen benötigt werden, desto besser.
Akf
0

Wenn der Javadoc nichts hinzufügt, lösche ich den Javadoc und verwende die automatisch generierten Kommentare.

Alex B.
quelle
0

Ich fülle immer beides aus. Der zusätzliche Schreibaufwand ist vernachlässigbar und mehr Informationen sind im Allgemeinen besser als weniger.

Paul Sonier
quelle
Sie sind nur dann selbsterklärend, wenn Sie sagen "Dies ist ein Eigenschaftssetzer". Andernfalls hat ein Client der API keine Ahnung, was tatsächlich in den Methoden passiert
oxbow_lakes
1
Wer hat etwas über Selbsterklärungen gesagt?
Paul Sonier