Einfache Getter / Setter Kommentare

Question

Welche Konvention verwenden Sie Getter und Setter zu kommentieren? Dies ist etwas, das ich schon seit geraumer Zeit gefragt habe, zum Beispiel:

/**
 * (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, dass ich immer ziemlich finden bin genau die gleiche Sache für 1a / b Schreiben und 2a / b, so etwas wie 1a) Stellt den Gehalt des Mitarbeiters, 1b) das Gehalt des Mitarbeiters. Es scheint nur so überflüssig. Jetzt konnte ich etwas sehen komplexere Sie mehr in den (a) Teile schreiben könnte, Kontext zu geben, aber für die Mehrheit der Getter / Setter gibt der Wortlaut ist fast genau das gleiche.

Ich bin nur neugierig, wenn für die einfachen Getter / its ok Setter nur entweder in dem (a) Teil zu füllen oder den (b) Teil.

Was denken Sie?

Answer 1

ich in der Regel füllen Sie einfach das param Teil für Einrichter, und die @return Teil für Getter:

/**
 * 
 * @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 javadoc Prüfwerkzeuge (wie Eclipse Warnungen) wird kommen sauber, und es gibt keine Überschneidungen.

Answer 2

Absolut sinnlos - du bist ohne diese Art von Mist besser unübersichtlich Code:

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

Sehr nützlich, wenn eine Garantie übernommen:

/**
 * 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);

Vor allem die Erklärung dessen, was Eigentum bedeutet eigentlich in Domain-Modelle entscheidend sein. Jedes Mal, wenn ich eine Bohne volle Eigenschaften mit obskuren Namen sehen, die nur Investmentbanker, Biochemiker oder Quantenphysiker verstehen, und die Kommentare zu erklären, dass die setGobbledygook () -Methode „das Geschwafel setzt.“, Ich will jemanden erwürgen.

Answer 3

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

Ich weiß, dass wie eine Nicht-Antwort klingt, aber ich versuche, meine Zeit zu verwenden, um zu kommentieren Dinge, die einer Erklärung bedürfen.

Answer 4

würde ich sagen, nur Sorgen über Getter und Setter zu kommentieren, wenn sie irgendeine Art von Nebenwirkung haben, oder eine Art Vorbedingung erfordern außerhalb der Initialisierung (dh immer ein Element aus einer Datenstruktur entfernen oder zu setzen, um etwas müssen Sie x und y an seinem Platz haben zuerst). Ansonsten sind die Kommentare sind hier ziemlich überflüssig.

Edit: Außerdem, wenn Sie eine Menge von Nebenwirkungen finden Sie beteiligt sind, in Ihrem Getter / Setter, möchten Sie vielleicht die Getter / Setter ändern, um eine andere Methode Namen haben (zB: Push und Pop für einen Stapel) [Danke für die Kommentare unten]

Answer 5

Fragen Sie sich, was wollen Sie Leute sehen, wenn die Kommentare als JavaDocs angesehen werden (von einem Browser). Viele Leute sagen, dass die Dokumentation nicht notwendig ist, da es offensichtlich ist. Dies wird nicht halten, wenn das Feld privat ist (es sei denn, Sie explizit für private Felder auf JavaDocs drehen).

In Ihrem Fall:

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

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

Wenn Setter / Getter dokumentieren, Ich mag das trennen, was von der Codierung. Beispiel:

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

Die erste Zeile sagt es die Höhe zurück. Der Rückgabeparameter Dokumente, die Höhe in Metern.

Answer 6

Warum sie enthalten nicht nur einen Referenz-Tag Sie den Feldwert und die Referenz von Getter und Setter Kommentar zu lassen.

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

public String getFoo() {
  return foo;
}

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

Damit die Dokumentation gilt für die Getter und Setter sowie das Feld (wenn private javadocs eingeschaltet ist, dass ist).

Answer 7

Diese Art von Textvorschlag kann mit Projekt Lombok vermieden werden. dokumentieren Sie einfach die Feldvariable, auch wenn es private ist, und lassen Sie Lombok Anmerkungen erzeugen ordnungsgemäß dokumentiert Getter und Setter.

Für mich ist dieser Vorteil allein lohnt sich die Kosten .

Answer 8

Ich bin wirklich enttäuscht über die Antworten im Grunde sagen, umfassende Dokumentation eine Zeitverschwendung ist. Wie werden die Kunden Ihrer API wissen soll, dass eine Methode namens setX ist ein Standard JavaBean Eigenschaft Setter es sei denn, sagen Sie so deutlich in der Dokumentation ?

Ohne Dokumentation würde ein Anrufer überhaupt keine Ahnung, ob die Methode Nebenwirkungen hatte, anders als durch ihre Finger über die scheinbare Konvention gefolgt Kreuzung wird.

Ich bin sicher, ich bin nicht der einzige hier, um das Unglück auf die harte Art und Weise, um herauszufinden, gehabt zu haben, dass ein Verfahren namens setX tut eine ganze Menge mehr als nur eine Eigenschaft festgelegt.

Answer 9

Wenn es gibt nicht spezielle Operation in Getter / Setter I in der Regel schreiben:

Mit Javadoc (mit eigener 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 eigener Extrakt Option):

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

/** @return #salary. */
public float salary();

Answer 10

Accessoren kommentieren, vor allem, wenn sie überall irgendwelche Operationen nicht tun, ist unnötig und eine Verschwendung von Fingerspitzen.

Wenn jemand den Code lesen kann nicht verstehen, dass person.getFirstName() den Vornamen einer Person zurückgibt, sollten Sie alles in Ihrer Kräfte versuchen, ihn gefeuert werden. Wenn es einige Datenbank Magie tut, wirft ein paar Würfel, ruft den Sekretär von Vornamen den Vornamen zu bekommen, ist sicher anzunehmen, es sich um eine nicht-triviale Operation ist, und dokumentieren es gut.

Wenn auf der anderen Seite, Ihr person.getFirstName() kehrt nicht den Vornamen der Person ... na ja, lassen Sie uns nicht dorthin gehen, sollen wir?

Answer 11

Sie nichts bringen, wenn der Feldname suficiently beschreibend für die Inhalte ist.

Im Allgemeinen lassen Sie den Code selbststehend sein, und vermeiden, wenn überhaupt möglich zu kommentieren. Dies kann Refactoring erfordern.

EDIT: Die oben bezieht sich auf Getter und Setter nur. Ich glaube, dass irgendetwas nicht trivial sollte richtig javadoc'ed werden.

Answer 12

Es ist in Ordnung, in der (b) Teil zu füllen, vor allem wenn Sie einen Kommentar auf der Felddeklaration setzen angibt, was das Feld ganz ist.

Answer 13

Wenn die javadoc der nichts hinzuzufügen, ich die javadoc löschen und verwenden Sie die automatisch generierten Kommentare.

Answer 14

Ich fülle immer in beide. Die zusätzliche Zeit verbrachte Typisierung vernachlässigbar ist, und weitere Informationen sind besser als weniger, im Allgemeinen.

Answer 15

Wenn es ein Getter / Setter ist, sollte es dokumentiert werden.

ich schweife hier, aber wenn es eine Eigenschaft gemacht werden kann, das ist vielleicht besser für eine einfachere Codierung der Benutzer der Klasse. Ich schweife weiter, aber wie für alle Kommentare, die „Java“ überall in ihnen haben, der sagte, es sei Java? (Die Tags, aber die Frage könnte überall wirklich anwenden)