Comentarios sobre el método reemplazado en Java

Question

¿Deberíamos comentar el método reemplazado o no? En caso afirmativo, ¿entonces si el comentario será un Java Doc o un simple comentario?

Answer 1

@ La respuesta de SimonC explica cómo la utilidad javadoc genera la documentación "heredada" para los métodos anulados.

También puede poner explícitos javadocs en un método de anulación y tendrán prioridad sobre los heredados javadocs. Además, si coloca la etiqueta {@inheritDoc} en los javadocs explícitos del método de anulación, los comentarios heredados se incluirán en ese punto.

Para responder a esta:

¿Hay que comentar el método reemplazado o no? En caso afirmativo, ¿entonces si el comentario será un Java Doc o un simple comentario?

En mi opinión, si el método de reemplazo refina la semántica documentados (contrato) del método reemplazado (o ... Dios no lo quiera ... rompe el contrato), entonces esto merece ser documentado en la anulación del método javadocs. Sin embargo, si las diferencias son meramente "detalles de implementación", entonces los comentarios simples (o ningún comentario) son más apropiados.

(Sin embargo, la práctica de incluir un comentario "no javadoc" que remite al lector al javadoc del método anulado es, IMO, un desperdicio de la pantalla de bienes raíces ... cuando estoy leyendo el código fuente.)

Answer 2

De How to Write Doc Comments for the Javadoc Tool:

automático de re-uso del método comenta

doc

Usted puede evitar volver a escribir comenta por ser consciente de cómo la herramienta Javadoc duplicados (hereda) comentarios para métodos que anula o implementa otros métodos. Esto ocurre en tres casos: Cuando un método en una clase anula un método en una superclase Cuando un método en una interfaz anula un método en un superinterfaz Cuando un método en una clase implementa un método en una interfaz en el primero dos casos, si un método m() anula otro método, la herramienta Javadoc generará un subtítulo "Sobrescribe" en la documentación para m(), con un enlace al método que está anulando.

En el tercer caso, si un método m() en una clase dada implementa un método en el una interfaz, la herramienta Javadoc se generar un subtítulo "especificado por" en la documentación para m(), con un enlace al método que está implementando.

En estos tres casos, si el método m() no contiene comentarios doc o etiquetas, la herramienta Javadoc también copiará el texto del método es primordial o la aplicación de la documentación generada por metro(). Por lo tanto, si es suficiente la documentación del método reemplazado o implementado, usted no necesita agregar documentación para m(). Si agrega cualquier documentación comentario o etiqueta a m(), la "Omitir" o el subtítulo "Especificado por" y el enlace seguirán apareciendo, pero no se copiará ningún texto .