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

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

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.

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

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

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.

@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.

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.

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.