¿Es una práctica correcta agregar comentarios de Javadoc en la interfaz y agregar comentarios que no sean de Javadoc en la implementación?¿Se deberían agregar los comentarios de Javadoc a la implementación?
La mayoría de los entornos de desarrollo generan los comentarios no Javadoc para implementaciones cuando Generar automáticamente los comentarios. ¿No debería el método concreto tener la descripción?
Para los métodos de aplicación que son solamente (no anula), claro, por qué no, sobre todo si son públicos.
Si usted tiene una situación de primer orden y que se va a reproducir cualquier texto, entonces 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 acotación al margen, si su versión primordial añade cosas a la documentación del supertipo, usted 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.
hacer frente a este problema fue una de las principales características de la herramienta prototipo que he construido - Cada vez que se invoca un método, te tengo una indicación de si su objetivo o cualquier posibles objetivos primordiales contenían 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.
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)
{ ... }
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.
@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.
OMI usando' @ see' ligarse a interactuar métodos es una buena práctica y que es suficiente en la mayoría de los casos . Cuando copia javadoc del método de interfaz a una implementación concreta, solo duplica la información y puede volverse rápidamente inconsistente. Sin embargo, cualquier información adicional sobre la implementación se debe agregar a javadoc. – Piotr
El documento adicional que no se trata de copiar el documento de la interfaz, pero sólo para explicar cómo se implementa el método y cosas por el estilo. Con un documento de interfaz, explique cuáles son los resultados/objetivos (estado de la aplicación o método de retorno), mientras que en su implementación podría ser útil explicar cómo logra estos objetivos. – redben
Algo buena práctica es poner
/**
* {@inheritDoc}
*/
como javadoc de aplicación (a menos que haya algo más que ser explicado por los detalles de la implementación).
El punto de tener una interfaz es que el método se puede implementar de múltiples maneras. Si voy a heredar los comentarios, ¿de qué sirve tener el comentario en la implementación? –
Uso la etiqueta anterior y luego coloco toda la documentación adicional requerida debajo de la etiqueta. –
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 la aplicación debe tener en cuenta las ampliaciones o restricciones en el contrato, así como detalles apropiados de la aplicación, en especial de rendimiento.
En general, cuando se reemplaza un método, que se adhieren al contrato definido en la clase base/interfaz, por lo que no quieren cambiar el javadoc original de todos modos. Por lo tanto, el uso de la etiqueta @inheritDoc o @see mencionado en otras respuestas no es necesario y, en realidad, solo sirve como un ruido en el código.Todas las herramientas sensibles heredan 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 (! Estoy mirando a ti, Eclipse) generan éstos de forma predeterminada al sustituir un método sólo es una triste estado de las cosas, pero no justifica abarrotar su código con ruido inútil.
Por supuesto, puede ser el caso contrario, cuando en realidad se desea agregar un comentario al método predominante (por lo general algunos detalles de implementación adicionales o hacer el contrato un poco más estricta). Pero en este caso, casi nunca quiere 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, simplemente escriba la parte de su propio comentario y eso es todo. Todas las herramientas javadoc siempre muestran algún tipo de especificado por vínculo que puede hacer clic para leer el comentario de la clase base. No tiene sentido mezclarlos.
Esta es la única respuesta correcta aquí! – user219882
¿No sabe que los elementos deben ser comparables cuando se usa TreeMap? Una implementación tampoco debería implementar un comportamiento conflictivo. –
creo que esto debería ser la respuesta correcta http://stackoverflow.com/a/39981265/419516 – user219882