Commenti Getter / Setter semplici

Question

Quale convenzione usi per commentare getter e setter? Questo è qualcosa che mi chiedevo da un po 'di tempo, ad esempio:

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

Trovo sempre che scrivo praticamente la stessa cosa per 1a / b e 2a / b, qualcosa come 1a) Imposta lo stipendio dell'impiegato, 1b) lo stipendio dell'impiegato. Sembra così ridondante. Ora potrei vedere qualcosa di più complesso che potresti scrivere di più nelle parti (a), per dare un contesto, ma per la maggior parte dei getter / setter là fuori il testo è quasi esattamente lo stesso.

Sono solo curioso di sapere se, per i getter / setter semplici, è sufficiente compilare solo la parte (a) O la parte (b).

Cosa ne pensi?

Answer 1

Di solito riempio solo la parte param per setter e la parte @return per 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();

In questo modo gli strumenti di controllo javadoc (come gli avvertimenti di Eclipse) risulteranno puliti e non ci saranno duplicazioni.

Answer 2

Assolutamente inutile: stai meglio senza questo tipo di schifezze che ingombrano il tuo codice:

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

Molto utile, se garantito:

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

Soprattutto la spiegazione di cosa significhi effettivamente la proprietà può essere cruciale nei modelli di dominio. Ogni volta che vedo un fagiolo pieno di proprietà con nomi oscuri che solo i banchieri di investimento, i biochimici o i fisici quantistici comprendono, e i commenti spiegano che il metodo setGobbledygook () " imposta il gobbledygook. & Quot ;, Voglio strangolare qualcuno.

Answer 3

In genere nulla, se posso evitarlo. Getter e setter dovrebbero essere autoesplicativi.

So che sembra una non risposta, ma cerco di usare il mio tempo per commentare cose che necessitano di spiegazione.

Answer 4

Direi solo di preoccuparmi di commentare getter e setter se hanno una sorta di effetto collaterale, o richiedono una sorta di precondizione al di fuori dell'inizializzazione (ad es. qualcosa che devi prima avere xey in posizione). Altrimenti i commenti qui sono piuttosto ridondanti.

Modifica: Inoltre, se trovi molti effetti collaterali coinvolti nel tuo getter / setter, potresti voler cambiare il getter / setter per avere un nome di metodo diverso (ad esempio: push e pop per uno stack) [Grazie per i commenti qui sotto]

Answer 5

Chiediti cosa vuoi che le persone vedano quando i commenti vengono visualizzati come JavaDocs (da un browser). Molte persone dicono che la documentazione non è necessaria poiché è ovvia. Questo non sarà valido se il campo è privato (a meno che non si attivi esplicitamente JavaDocs per i campi privati).

Nel tuo caso:

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

Non è chiaro in che cosa è espresso lo stipendio. Sono centesimi, dollari, sterline, RMB?

Quando documento setter / getter, mi piace separare il cosa dalla codifica. Esempio:

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

La prima riga dice che restituisce l'altezza. Il parametro di ritorno documenta che l'altezza è espressa in metri.

Answer 6

Perché non includono semplicemente un tag di riferimento per farti commentare il valore del campo e il riferimento da getter e setter.

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

public String getFoo() {
  return foo;
}

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

In modo che la documentazione si applichi al getter, al setter e al campo (se è attivato javadocs privato, cioè).

Answer 7

Questo tipo di boilerplate può essere evitato usando Project Lombok . Basta documentare la variabile di campo, anche se è private , e lasciare che le annotazioni di Lombok generino getter e setter adeguatamente documentati.

Per me, questo vantaggio da solo vale i costi .

Answer 8

Sono davvero deluso dalle risposte in sostanza dicendo che la documentazione completa è una perdita di tempo. In che modo i clienti della tua API dovrebbero sapere che un metodo chiamato setX è un setter di proprietà JavaBean standard a meno che non lo dica chiaramente nella documentazione ?

Senza documentazione, un chiamante non avrebbe alcuna idea se il metodo avesse effetti collaterali, se non incrociando le dita sull'apparente convenzione seguita.

Sono sicuro di non essere l'unico qui ad avere avuto la sfortuna di scoprire nel modo più duro che un metodo chiamato setX fa molto di più che impostare una proprietà.

Answer 9

Se non ci sono operazioni speciali in getter / setter di solito scrivo:

Con Javadoc (con opzione privata):

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

e / o

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

Con Doxygen (con opzione di estrazione privata):

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

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

Answer 10

Gli accessor ai commenti, specialmente se non eseguono operazioni da nessuna parte, non sono necessari e sprecano la punta delle dita.

Se qualcuno che legge il tuo codice non riesce a capire che person.getFirstName () restituisce il nome di una persona, dovresti provare tutto ciò che è in tuo potere per farlo licenziare. Se fa un po 'di magia nel database, lancia qualche dado, chiama il segretario dei nomi per ottenere il nome, è sicuro presumere che sia un'operazione non banale e documentalo bene.

Se, d'altra parte, il tuo person.getFirstName () non restituisce il nome di una persona ... beh, non andiamo lì, vero?

Answer 11

Non inserire nulla se il nome del campo è sufficientemente descrittivo del contenuto.

Generalmente, lascia che il codice sia autonomo ed evita di commentare se possibile. Ciò potrebbe richiedere il refactoring.

EDIT: quanto sopra si riferisce solo a getter e setter. Credo che qualsiasi cosa non banale debba essere opportunamente javadocata.

Answer 12

va bene compilare la parte (b), specialmente se si inserisce un commento nella dichiarazione del campo indicando di cosa tratta il campo.

Answer 13

Se javadoc non aggiunge nulla, cancello javadoc e utilizzo i commenti generati automaticamente.

Answer 14

Compilare sempre entrambi. Il tempo aggiuntivo impiegato a scrivere è trascurabile, e più informazioni sono meglio che meno, in generale.

Answer 15

Se è un getter / setter, dovrebbe essere documentato.

Sto divagando qui, ma se si può fare una proprietà, forse è meglio per una codifica più semplice degli utenti della classe. Sto divagando ulteriormente, ma come per tutti i commenti che hanno "java" ovunque in loro, chi ha detto che era Java? (i tag, ma la domanda potrebbe applicarsi davvero ovunque)