Manera SECA de escribir Javadoc en métodos de sobrecarga

Respuestas:

3

Asperjo {@inheritDoc}directivas aquí y allá en mis comentarios Javadoc al anular métodos de superclases o implementar métodos definidos por la interfaz.

Esto funciona bien para mí al menos, evita la repetición en el código fuente, y aún puede agregar información específica al comentario particular de Javadoc si es necesario hacerlo. No considero que el comentario de Javadoc en sí sea bastante simple para ser un problema cuando todo lo que se necesita en un IDE decente es pasar el cursor sobre el nombre del identificador asociado para obtener el Javadoc representado con referencias y todo.

un CVn
fuente
2

El objetivo de la documentación es iluminar a los futuros usuarios de un artículo. Esto es en parte para la conveniencia del autor, para que él o ella no tenga que ser contactado siempre que alguien no pueda entender cómo funciona la cosa. Sin embargo, principalmente es para el beneficio de las personas que necesitan usar o apoyar la cosa.

Como tal, el punto debe ser la claridad, en lugar de la conveniencia para el autor. No puede esperar que las personas busquen su documentación de API porque era demasiado vago para repetirlo. Absórbalo: Javadoc será repetitivo.

Dicho esto, no hay razón, si eres inteligente, no puedes escribir un programa que pegue comentarios en tu código basado en marcadores u otros criterios. Puede ser más problema de lo que vale. O no.

Matthew Flynn
fuente
44
No, no te repitas; es mucho más sobrecarga para mantener todo sincronizado. Si hay nueva información sobre la implementación sobrecargada, escriba solo eso. Creo que ES razonable esperar que los usuarios de un tipo vean los javadocs de sus supertipos, y herramientas como Eclipse les facilitan hacerlo.
Dawood ibn Kareem