Einfache Getter / Setter-Kommentare

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?

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.

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.

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.

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]

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.

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

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 .

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.

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();

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?

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.

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.

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

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