Semplici commenti Getter / Setter

Quale convenzione usi per commentare getter e setter? Questo è qualcosa che mi chiedo 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 sto scrivendo più o meno la stessa identica cosa per 1a / be 2a / b, qualcosa come 1a) Imposta lo stipendio del dipendente, 1b) lo stipendio del dipendente. Sembra così ridondante. Ora potrei vedere per 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 la formulazione è quasi esattamente la stessa.

Sono solo curioso se, per i semplici getter / setter, va bene compilare solo la parte (a) OPPURE la parte (b).

Cosa ne pensi?

Di solito riempio solo la parte param per i setter e la parte @return per i 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 avvisi di Eclipse) risulteranno puliti e non ci saranno duplicazioni.

Assolutamente inutile: stai meglio senza questo tipo di schifezze che ingombra 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 del significato effettivo della proprietà può essere cruciale nei modelli di dominio. Ogni volta che vedo un fagiolo pieno di proprietà con nomi oscuri che solo banchieri di investimento, biochimici o fisici quantistici capiscono, e i commenti spiegano che il metodo setGobbledygook () "imposta il gobbledygook.", Voglio strangolare qualcuno.

Generalmente niente, se posso evitarlo. Getter e setter dovrebbero essere autoesplicativi.

So che suona come una non risposta, ma cerco di usare il mio tempo per commentare cose che necessitano di spiegazioni.

Direi che ti preoccupi solo di commentare getter e setter se hanno una sorta di effetto collaterale o richiedono una sorta di precondizione al di fuori dell'inizializzazione (ad esempio: ottenere rimuoverà un elemento da una struttura dati o per impostare qualcosa di cui hai bisogno avere xey al loro posto per primi). Altrimenti i commenti qui sono piuttosto ridondanti.

Modifica: Inoltre, se trovi che molti effetti collaterali sono 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 sotto]

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

Nel tuo caso:

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

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

Quando si documentano 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 è in metri.

Perché non includono solo un tag di riferimento per consentire di 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 e al setter oltre che al campo (se javadocs privato è attivato).

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

Per me, questo vantaggio da solo vale i costi .

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

Senza documentazione, un chiamante non avrebbe idea se il metodo avesse effetti collaterali, a parte l'incrocio delle dita sull'apparente convenzione seguita.

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

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

Commentare le funzioni di accesso, soprattutto se non eseguono alcuna operazione da nessuna parte, è inutile e uno spreco di dita.

Se qualcuno che legge il tuo codice non riesce a capirlo 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 alcuni dadi, chiama il Segretario dei nomi per ottenere il nome, è lecito ritenere che sia un'operazione non banale e documentarla bene.

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

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

In generale, 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 dovrebbe essere correttamente javadoc'ed.

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

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

Compilo sempre entrambi. Il tempo aggiuntivo dedicato alla digitazione è trascurabile e più informazioni sono meglio di meno, in generale.