Comentarios simples de Getter / Setter

¿Qué convención usas para comentar captadores y establecedores? Esto es algo que me he preguntado durante bastante tiempo, por ejemplo:

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

Siempre encuentro que estoy escribiendo exactamente lo mismo para 1a / by 2a / b, algo así como 1a) Establece el salario del empleado, 1b) el salario del empleado. Simplemente parece tan redundante. Ahora podría ver algo más complejo que podría escribir más en las partes (a), para dar contexto, pero para la mayoría de los captadores / establecedores, la redacción es casi exactamente la misma.

Solo tengo curiosidad si, para los captadores / establecedores simples, está bien completar solo la parte (a) O la parte (b).

¿Qué piensas?

Por lo general, solo lleno la parte param para setters, y la parte @return para getters:

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

De esa forma, las herramientas de comprobación de javadoc (como las advertencias de Eclipse) saldrán limpias y no habrá duplicación.

Absolutamente inútil: estás mejor sin este tipo de basura que satura tu código:

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

Muy útil, si se justifica:

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

Especialmente la explicación de lo que realmente significa la propiedad puede ser crucial en los modelos de dominio. Cada vez que veo un bean lleno de propiedades con nombres oscuros que solo entienden los banqueros de inversión, los bioquímicos o los físicos cuánticos, y los comentarios explican que el método setGobbledygook () "establece el gobbledygook", quiero estrangular a alguien.

Generalmente nada, si puedo evitarlo. Getters y setters deben explicarse por sí mismos.

Sé que eso suena como una falta de respuesta, pero trato de usar mi tiempo para comentar cosas que necesitan explicación.

Diría que solo se preocupe por comentar getters y setters si tienen algún tipo de efecto secundario, o requieren algún tipo de condición previa fuera de la inicialización (es decir: obtener eliminará un elemento de una estructura de datos, o para establecer algo que necesita tener x e y en su lugar primero). De lo contrario, los comentarios aquí son bastante redundantes.

Editar: Además, si encuentra que hay muchos efectos secundarios involucrados en su captador / definidor, es posible que desee cambiar el captador / definidor para que tenga un nombre de método diferente (es decir, presione y explote para una pila) [Gracias por los comentarios a continuación]

Pregúntese qué quiere que la gente vea cuando los comentarios se ven como JavaDocs (desde un navegador). Mucha gente dice que la documentación no es necesaria ya que es obvia. Esto no se mantendrá si el campo es privado (a menos que active explícitamente JavaDocs para campos privados).

En tu caso:

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

No está claro en qué salario se expresa. ¿Son centavos, dólares, libras, RMB?

Al documentar setters / getters, me gusta separar el qué de la codificación. Ejemplo:

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

La primera línea dice que devuelve la altura. El parámetro de retorno documenta que la altura está en metros.

¿Por qué no solo incluyen una etiqueta de referencia para permitirle comentar el valor del campo y la referencia de captadores y definidores?

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

public String getFoo() {
  return foo;
}

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

Para que la documentación se aplique al getter y setter, así como al campo (si está activado javadocs privados, eso es).

Este tipo de repetitivo puede evitarse utilizando Project Lombok . Simplemente documente la variable de campo, incluso si esprivate , y deje que las anotaciones de Lombok generen getters y setters debidamente documentados.

Para mí, este beneficio sólo vale la pena los costos .

Estoy realmente decepcionado con las respuestas, básicamente diciendo que la documentación exhaustiva es una pérdida de tiempo. ¿Cómo se supone que los clientes de su API deben saber que un método llamado setXes un configurador de propiedades JavaBean estándar a menos que lo indique claramente en la documentación ?

Sin documentación, la persona que llama no tendría idea de si el método tuviera algún efecto secundario, aparte de cruzar los dedos sobre la aparente convención que se está siguiendo.

Estoy seguro de que no soy el único aquí que ha tenido la desgracia de descubrir de la manera difícil que un método llamado setXhace mucho más que simplemente establecer una propiedad.

Si no hay una operación especial en getter / setter, generalmente escribo:

Con Javadoc (con opción privada):

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

y / o

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

Con Doxygen (con opción de extracto privado):

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

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

Comentar los accesores, especialmente si no realizan ninguna operación en ningún lado, es innecesario y es un desperdicio de dedos.

Si alguien que lee su código no puede entender eso person.getFirstName() devuelve el nombre de una persona, debe intentar todo lo que esté a su alcance para que lo despidan. Si hace algo de magia en la base de datos, arroja algunos dados, llama al Secretario de Nombres para obtener el primer nombre, es seguro asumir que es una operación no trivial y documentarlo bien.

Si, por otro lado, person.getFirstName()no devuelve el nombre de una persona ... bueno, no vayamos allí, ¿de acuerdo?

No ponga nada si el nombre del campo es suficientemente descriptivo de los contenidos.

En general, deje que el código sea autónomo y evite comentar si es posible. Esto puede requerir refactorización.

EDITAR: Lo anterior se refiere solo a captadores y establecedores. Creo que todo lo que no sea trivial debe ser javaccado correctamente.

está bien completar la parte (b), especialmente si pone un comentario en la declaración del campo que indica de qué se trata el campo.

Si el javadoc no agrega nada, elimino el javadoc y uso los comentarios generados automáticamente.

Yo siempre lleno los dos. El tiempo adicional dedicado a escribir es insignificante y, en general, más información es mejor que menos.