programa - ¿Deben agregarse los comentarios de Javadoc a la implementación?

javadoc pdf

Question

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

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

Answer 1

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

Answer 2

En general, 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 ninguna manera. Por lo tanto, el uso de @inheritDoc o etiqueta @see mencionado en otras respuestas no es necesario y, de hecho, solo sirve como un ruido en el código. Todas las herramientas sensatas heredan el método javadoc de la superclase o interfaz como se especifica here :

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 genera por defecto cuando anular un método es solo un triste estado de cosas, pero no justifica abarrotar tu código con ruido inútil.

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

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

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

Answer 3

Para los métodos que son solo de implementación (no reemplazos), seguro, por qué no, especialmente si son públicos.

Si tiene una situación primordial y va a replicar cualquier texto, definitivamente no. La replicación es una forma infalible de causar 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 el subtipo. Use @inheritDoc o no proporcione una documentación: los IDE tomarán el texto disponible más bajo para usar en su vista de Javadoc.

Como comentario aparte, 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 estará al tanto de la información adicional en la versión principal si invocan a través de un supertipo.

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

Answer 4

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

Answer 5

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 necesita, qué valores debe devolver y qué debe hacer en caso de error.

La documentación de implementación debe tener en cuenta las extensiones o restricciones del contrato, y también los detalles apropiados de la implementación, especialmente el rendimiento.

Answer 6

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)
{ ... }

Answer 7

Una buena práctica es poner

/**
* {@inheritDoc}
*/

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