java - annotation - Comentarios simples de Getter/Setter

spring boot getter setter annotation

Question

¿Qué convención usas para comentar getters y setters? 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 / instaladores la redacción es casi exactamente la misma.

Solo tengo curiosidad si, para los getters / setters simples está bien solo rellenar la parte (a) O la parte (b).

¿Qué piensas?

Answer 1

¿Por qué no solo incluyen una etiqueta de referencia que le permite comentar el valor del campo y la referencia de getters y setters?

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

public String getFoo() {
  return foo;
}

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

De modo que la documentación se aplica al getter y al setter, así como también al campo (si javascriptcs privados están activados).

Answer 2

Absolutamente inútil: estarás mejor sin este tipo de basura abarrotando tu código:

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

Muy útil, si está justificado:

/**
 * 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 frijol lleno de propiedades con nombres oscuros que solo los banqueros de inversión, los bioquímicos o los físicos cuánticos entienden, y los comentarios explican que el método setGobbledygook () "establece el gilipollas", quiero estrangular a alguien.

Answer 3

Comentar accesos, especialmente si no hacen ninguna operación en cualquier lugar, es innecesario y un desperdicio de dedos.

Si alguien que lee tu código no puede entender a esa person.getFirstName() devuelve el primer nombre de una persona, debes probar todo lo que esté a tu alcance para que lo despidan. Si realiza alguna magia en la base de datos, arroja unos cuantos dados, llama al Secretario de los Nombres para obtener el primer nombre, es seguro asumir que es una operación no trivial y documentarla bien.

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

Answer 4

En general nada, si puedo evitarlo. Getters y setters deben ser autoexplicativos.

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

Answer 5

Este tipo de repetición puede evitarse utilizando Project Lombok . Solo 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 la pena los costs .

Answer 6

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

Sin documentación, la persona que llama no tendría idea alguna si el método tuvo algún efecto secundario, más que cruzando los dedos sobre la aparente convención que se sigue.

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

Answer 7

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

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

EDITAR: Lo anterior se refiere a getters y setters solamente. Creo que cualquier cosa no trivial debe ser apropiadamente javadoc''ed.

Answer 8

Pregúntese qué desea que las personas vean cuando los comentarios se vean como JavaDocs (desde un navegador). Mucha gente dice que la documentación no es necesaria ya que es obvio. Esto no se mantendrá si el campo es privado (a menos que encienda 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. ¿Es centavos, dólares, libras, RMB?

Al documentar setters / getters, me gusta separar lo que 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 9

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

Answer 10

Si es un getter / setter, debe estar documentado.

Estoy divagando aquí, pero si se puede hacer una propiedad, tal vez sea mejor para una codificación más simple de los usuarios de la clase. Me estoy desviando un poco más, pero en cuanto a todos los comentarios que tienen "java" en algún lugar de ellos, ¿quién dijo que era java? (las etiquetas, pero la pregunta podría aplicarse en cualquier lugar realmente)

Answer 11

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 la opción de extracción privada):

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

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

Answer 12

Siempre llené ambos. El tiempo adicional dedicado a mecanografiar es insignificante, y en general, más información es mejor que menos.

Answer 13

Usualmente solo llené 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 esta forma, las herramientas de comprobación de javadoc (como las advertencias de Eclipse) saldrán limpias y no habrá duplicaciones.

Answer 14

Yo diría que solo me preocupo por comentar getters y setters si tienen algún tipo de efecto secundario, o requieren algún tipo de precondición fuera de la inicialización (es decir: get eliminará un elemento de una estructura de datos, o para establecer algo que necesita tener xey en primer lugar). De lo contrario, los comentarios aquí son bastante redundantes.

Editar: Además, si encuentra muchos efectos secundarios en su getter / setter, puede querer cambiar el getter / setter para que tenga un nombre de método diferente (es decir: push y pop para una pila) [Gracias por los comentarios a continuación]

Answer 15

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