Comentarios simples de Getter / Setter

124

¿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?

ThaDon
fuente
54
Como comentario aparte, nunca use float para nada monetario (como el salario aquí). Ver, por ejemplo, stackoverflow.com/questions/965831/…
Jonik
3
Use BigDecimal en su lugar.
Josep

Respuestas:

83

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.

sleske
fuente
¿Puedes arreglar el error tipográfico? "@return part for setters"
Jonik
1
También hay un error tipográfico en el comentario de salario (). No es un comentario JavaDoc.
Fostah
1
Estoy de acuerdo en que es el mejor enfoque para comentar accesores.
Fostah
30
Agregar ruido a su código en aras de silenciar la advertencia excesivamente pedante de nuestras herramientas me parece incorrecto. Si no agrega valor a un programador, entonces la solución correcta sería rechazar / corregir la verbosidad de las herramientas y / o disminuir lo mucho que nos importa saltar a través de los aros para que las herramientas nos recompensen. Se supone que las herramientas de análisis nos ayudan y ahorran esfuerzo, no crean más tareas sin sentido para nosotros.
Lyle
1
@Lyle Eso puede ser cierto, pero siento que casi siempre hay algo útil que un programador puede decir que describe un captador / definidor mejor que solo la firma del método solo. Sí, hay casos en los que un programador es perezoso y simplemente repite la firma del método en el comentario, pero creo que, en términos generales, es un comportamiento útil forzar.
Matt Vukas
174

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.

Michael Borgwardt
fuente
2
Mis sentimientos exactamente, lo peor son los modelos específicos de dominio donde solo un experto en dominio sabe lo que significa la propiedad.
ThaDon
77
Incluso si es útil, ¿qué haría para getFoo ()? ¿Copiarás el mismo comentario para getFoo () también?
Vinoth Kumar CM
3
@cmv: Obviamente, la parte "param" no se copiará. No estoy seguro de si el valor de tener la información adjunta a ambos accesos justifica directamente la duplicación de la información. Probablemente si. Aún mejor sería una forma de adjuntar un comentario a ambos; Creo que esto está disponible en Project Lombok.
Michael Borgwardt
@VinothKumar: tal vez sería mejor explicar simplemente la propiedad en el captador (como en "Foo es el factor de ajuste utilizado en el cálculo de la barra") y los efectos de cambiar el valor en el setter (o si es necesario o no inicializar ese valor: en el ejemplo de la respuesta no es necesario inicializar Foo ya que "tiene un valor predeterminado según el tipo de Baz").
Freitass
+1 para "nombres oscuros que solo entienden los banqueros de inversión, los bioquímicos o los físicos cuánticos"
Jackson
36

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.

Eric Wendelin
fuente
55
Otra respuesta válida en este sentido podría ser "los diseños con getters y setters no entienden adecuadamente la noción de encapsulación" :)
Trejkaz
2
@Trejkaz: No es cierto, porque los métodos de acceso permiten propiedades de solo lectura o solo de escritura, y para polimorfismo (y así envolver, proxy, etc.).
Laurent Pireyn
2
Pueden permitir esas cosas, pero a menudo un patrón de constructor puede reemplazar a los colocadores (menos mutable) o un patrón de visitante puede reemplazar a los captadores (más flexible)
Trejkaz
Ciertamente me gusta y uso el patrón de construcción, pero hay tanto apoyo para los POJO (por ejemplo, en Hibernate) que los captadores y los setters todavía tienen un lugar muy destacado, para bien o para mal. Es lo más dañino de Java, en mi humilde opinión, y después de escribir JavaDocs repetitivos durante más de una década, estoy a punto de suscribirme a los consejos de @ sleske.
Michael Scheper
34

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]

Gopherkhan
fuente
10
podría decirse que debe cambiar el nombre de los captadores que tienen efectos secundarios para que sea más claro, ya que no todos los desarrolladores leerán los comentarios.
akf
Eso está bien, pero eso requiere que los usuarios de su API sepan que, si hubiera habido efectos secundarios, ¡ habrían sido documentados !
oxbow_lakes
akf, estaba pensando exactamente eso después de publicar :) Creo que lo agregaré a mi respuesta.
Gopherkhan
1
pero si no documenta los captadores y establecedores "estúpidos" (¡es lo que prefiero también!), ¿cómo se deshace de las advertencias de Eclipse sobre javadoc perdido? No quiero saturar mi espacio de trabajo con advertencias como esa, pero tampoco quiero que esa advertencia se deshabilite para todos los demás métodos ...
Zordid
12

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.

Steve Kuo
fuente
1
Si bien estoy de acuerdo con usted, creo que uno debe asegurarse de que los comentarios de la función no tengan en cuenta un nombre de función no explícito, mal elegido.
karlipoppins
Soy un gran defensor de JavaDocs, pero también un gran defensor del código autodocumentado. Entonces, al menos para la acomodadora, haría algo comopublic void setSalary(float aud) (o de manera más realista public void setSalary(BigDecimal aud)). Mejor aún, la propiedad debería ser de tipo abstract class CurrencyAmount, que a su vez tiene las propiedades java.util.Currency currencyy java.math.BigDecimal amount. La mayoría de los desarrolladores con los que he trabajado son terriblemente vagos con JavaDoc, pero hacer cumplir una API como esta hace que esto sea menos problemático.
Michael Scheper
Si la unidad es una unidad SI como metros / segundos, hay menos necesidad de documentar, si no es una unidad Si, entonces debe documentarse o nombrarse mejor para incluir la unidad no estándar, por ejemplo, alturaPies
AlexWien
8

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

Steve
fuente
Estoy de acuerdo. Y luego me di cuenta, ¿por qué escribir todo este repetitivo de todos modos? Vea mi respuesta sobre el Proyecto Lombok.
Michael Scheper
7

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 .

Michael Scheper
fuente
4

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.

oxbow_lakes
fuente
11
Sin documentación, cualquier persona que llame supondrá que un método llamado setX establece X. De ello se deduce que si setX realmente establece X, sin hacer nada más importante, entonces no necesita documentación.
mqp
¡Eso es genial! Ahora, ¿esta empresa CrudTech, cuya API estoy codificando, sigue su convención, o sigue a alguien más en este hilo? Hmmmm
oxbow_lakes
55
No tiene sentido escribir "establece el precio" en el documento setPrice si el método solo establece el valor de la propiedad de precio, pero si también, por ejemplo, actualiza la propiedad totalPrice y recalcula el impuesto, dicho comportamiento obviamente debería documentarse.
João Marcus
8
Parece que está solicitando la documentación que indique "Esto hace lo que espera". Lo cual es un poco como escribir "Precaución: CALIENTE" en una taza de café. En un mundo perfecto, no habría necesidad de decir tales cosas.
Kevin Panko
1
Sí, después de haber usado API donde los métodos llamados cosas setXtenían efectos secundarios distintos a los esperados, puedo afirmar con confianza que este no es un mundo perfecto.
oxbow_lakes
4

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();
TermWay
fuente
2
¡El problema con este enfoque es que Javadoc no genera la documentación privada por defecto! En ese caso, la etiqueta de referencia {@see #salary}no es válida en la documentación generada.
Jarek Przygódzki
1

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?

Henrik Paul
fuente
66
¿Qué pasa si getFirstName () devuelve nulo? ¿Dónde estaría eso documentado?
Steve Kuo
¿Qué hay de security.getFinalMaturity ()? No todos los nombres de propiedades tienen un significado inmediatamente comprensible. ¿Te gustaría ser despedido por no saber lo que eso significa?
Michael Borgwardt
¿Qué pasa si el método se implementa mediante swizzling? ¿Cómo se supone que debes saber eso a menos que esté claramente documentado? ¿Cómo se supone que debes saber que es un setter estándar a menos que el doctor lo diga?
oxbow_lakes
2
get / set debería, en mi opinión, estar reservado para getters y setters. Las búsquedas en la base de datos deben denominarse como "lookupPerson" o algo así.
Thorbjørn Ravn Andersen
1

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.

Thorbjørn Ravn Andersen
fuente
1
Hay una diferencia entre comentar y documentar.
Tom Hawtin - tackline
1
Muy cierto. Por lo tanto, es exactamente por eso que no comento getters y setters. Deben explicarse por sí mismos, y agregar un comentario indica que el código no se explica por sí mismo.
Thorbjørn Ravn Andersen
0

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.

akf
fuente
No está bien: la gente no lee los comentarios de campo. Javadoc ni siquiera genera la documentación privada de forma predeterminada, y los IDE no le muestran la documentación de campo cuando utiliza la ayuda rápida en una llamada al método.
Trejkaz
las personas no leen los comentarios de campo a menos que lo necesiten. Una vez que sea necesario, cuanta más información, mejor.
akf
0

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

Alex B
fuente
0

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

Paul Sonier
fuente
Solo se explican por sí mismos si dices "esto es un configurador de propiedades". De lo contrario, un cliente de la API tiene la menor idea de lo que realmente está sucediendo dentro de los métodos
oxbow_lakes
1
¿Quién dijo algo sobre auto explicativo?
Paul Sonier