¿Deberían agregarse comentarios de Javadoc a la implementación?

109

¿Es una práctica correcta agregar comentarios Javadoc en la interfaz y agregar comentarios que no sean Javadoc en la implementación?

La mayoría de los IDE generan comentarios que no son de JavaDoc para implementaciones cuando genera comentarios automáticamente. ¿No debería el método concreto tener la descripción?

Vaishak Suresh
fuente

Respuestas:

67

Para los métodos que son solo de implementación (no anulaciones), claro, ¿por qué no?

Si tiene una situación primordial y va a replicar cualquier texto, definitivamente no. La replicación es una forma infalible de provocar discrepancias. Como resultado, los usuarios tendrían una comprensión diferente de su método en función de si examinan el método en el supertipo o en el subtipo. Use @inheritDoco no proporcione una documentación: los IDE tomarán el texto más bajo disponible para usar en su vista Javadoc.

Como acotación al margen, si su versión principal agrega cosas a la documentación del supertipo, podría estar en un mundo de problemas. Estudié este problema durante mi doctorado y descubrí que, en general, la gente nunca se dará cuenta de la información adicional en la versión predominante si está invocando a través de un supertipo.

Abordar este problema fue una de las principales características de la herramienta de prototipo que construí: cada vez que invocaba un método, recibía una indicación de si su objetivo o cualquier objetivo principal potencial contenía información importante (por ejemplo, un comportamiento conflictivo). Por ejemplo, al invocar put en un mapa, se le recordó que si su implementación es un TreeMap, sus elementos deben ser comparables.

Uri
fuente
1
¿No sabe ya que los elementos deben ser comparables cuando se usa un TreeMap? Una implementación tampoco debería implementar un comportamiento conflictivo.
Jimmy T.
1
Creo que esta debería ser la respuesta correcta stackoverflow.com/a/39981265/419516
user219882
26

Tanto la implementación como la interfaz deben tener javadoc. Con algunas herramientas, puede heredar la documentación de la interfaz con la palabra clave @inheritDoc.

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }
Sjoerd
fuente
5
¿Qué son exactamente 'algunas herramientas'? ¿Funciona de inmediato o está vinculado a algunos complementos específicos?
Jediz
Sé que Eclipse usa {@inheritDoc}y solo funciona si no tiene la anotación @Overrideprimero
ksnortum
24

Algo buena práctica es poner

/**
 * {@inheritDoc}
 */

como javadoc de la implementación (a menos que haya algo adicional que explicar sobre los detalles de la implementación).

Vanya
fuente
2
El punto de tener una interfaz es que el método se puede implementar de múltiples maneras. Si solo voy a heredar los comentarios, ¿de qué sirve tener el comentario en la implementación?
Vaishak Suresh
16
Utilizo la etiqueta anterior y luego coloco cualquier documentación adicional requerida debajo de la etiqueta.
Ben Page
17

Generalmente, cuando anula un método, se adhiere al contrato definido en la clase / interfaz base, por lo que no desea cambiar el javadoc original de todos modos. Por lo tanto, el uso de la etiqueta @inheritDoco @seemencionado en otras respuestas no es necesario y en realidad solo sirve como ruido en el código. Todas las herramientas sensibles heredan el método javadoc de la superclase o interfaz como se especifica aquí :

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

El hecho de que algunas herramientas (¡te estoy mirando, Eclipse!) Las generen de forma predeterminada al anular un método es solo un estado triste de las cosas, pero no justifica saturar tu código con ruido inútil.


Por supuesto, puede ocurrir el caso contrario, cuando realmente desee agregar un comentario al método principal (generalmente algunos detalles de implementación adicionales o hacer que el contrato sea un poco más estricto). Pero en este caso, casi nunca querrás hacer algo como esto:

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

¿Por qué? Porque el comentario heredado posiblemente sea muy largo. En tal caso, ¿quién notará la oración adicional al final de los 3 párrafos largos? En cambio, simplemente escriba el fragmento de su propio comentario y eso es todo. Todas las herramientas de javadoc siempre muestran algún tipo de enlace Especificado por en el que puede hacer clic para leer el comentario de la clase base. No tiene sentido mezclarlos.

Natix
fuente
6

@see Genera un enlace a la descripción en la interfaz. Pero creo que también es bueno agregar algunos detalles sobre la implementación.

redben
fuente
6
En mi opinión, el uso @seede métodos de vinculación a interfaz es una buena práctica y es suficiente en la mayoría de los casos. Cuando copia javadoc de un método de interfaz a una implementación concreta, simplemente duplica la información y rápidamente puede volverse inconsistente. Sin embargo, cualquier información adicional sobre la implementación debe agregarse a javadoc.
Piotr
1
El documento adicional no se trata de copiar el documento de la interfaz, sino solo de explicar cómo implementa el método y cosas así. Con un documento de interfaz, explica cuáles son los resultados / objetivos (estado de la aplicación o retorno del método), mientras que en su implementación puede ser bueno explicar cómo logra estos objetivos.
redben
4

Sjoerd dice correctamente que tanto la interfaz como la implementación deben tener JavaDoc. La interfaz JavaDoc debe definir el contrato del método: qué debe hacer el método, qué entradas toma, qué valores debe devolver y qué debe hacer en caso de error.

La documentación de implementación debe incluir extensiones o restricciones en el contrato, y también detalles apropiados de la implementación, especialmente el desempeño.

DJClayworth
fuente
0

Por el bien de javadoc generado, sí, importa. Si declara referencias a una implementación concreta utilizando solo la interfaz, entonces no es así, ya que el IDE recuperará los métodos de la interfaz.

Boris Pavlović
fuente