Comentarios simples de Getter / Setter

Question

¿Qué convención utiliza 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 escribo 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.

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

¿Qué opinas?

Answer 1

Por lo general, solo lleno la parte param para los 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.

Answer 2

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.

Answer 3

Generalmente nada, si puedo evitarlo. Getters y setters deberían 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.

Answer 4

Yo 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: presionar y reventar para una pila) [Gracias por los comentarios a continuación]

Answer 5

Pregúntate qué quieres 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 su caso:

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

No está claro en qué salario se expresa. ¿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.

Answer 6

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

Answer 7

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

Para mí, este beneficio solo vale los costos .

Answer 8

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 setX es un configurador de propiedad JavaBean estándar a menos que lo indique claramente en la documentación ?

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

Estoy seguro de que no soy el único aquí que ha tenido la desgracia de descubrir por las malas que un método llamado setX hace mucho más que simplemente establecer una propiedad.

Answer 9

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

Answer 10

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 que 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 nombre, es seguro asumir que es una operación no trivial y documentarlo bien.

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

Answer 11

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

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

EDITAR: lo anterior se refiere solo a captadores y definidores. Creo que todo lo que no sea trivial debería ser javaccado correctamente.

Answer 12

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.

Answer 13

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

Answer 14

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

Answer 15

Si es un captador / configurador, debe documentarse.

Estoy divagando aquí, pero si se puede convertir en una propiedad, quizás eso sea mejor para una codificación más simple de los usuarios de la clase. Me desvío más, pero en cuanto a todos los comentarios que tienen "Java" en cualquier parte de ellos, ¿quién dijo que era Java? (las etiquetas, pero la pregunta podría aplicarse en cualquier lugar realmente)