¿Es necesario escribir un comentario javadoc para CADA parámetro en la firma de un método?

Uno de los desarrolladores de mi equipo cree que es necesario escribir un comentario de javadoc para CADA parámetro en la firma de un método. No creo que esto sea necesario, y de hecho creo que incluso puede ser dañino.

En primer lugar, creo que los nombres de los parámetros deberían ser descriptivos y autodocumentados. Si no es inmediatamente obvio para qué sirven sus parámetros, probablemente lo esté haciendo mal. Sin embargo, entiendo que a veces no está claro para qué sirve un parámetro, por lo que en esos casos, sí, debe escribir un comentario de javadoc que explique el parámetro.

Pero creo que es innecesario hacer eso para CADA parámetro. Si ya es obvio para qué sirve el parámetro, el comentario de javadoc es redundante; solo estás creando trabajo extra para ti. Además, está creando trabajo extra para cualquiera que tenga que mantener su código. Los métodos cambian con el tiempo, y mantener comentarios es casi tan importante como mantener su código. ¿Cuántas veces has visto un comentario como "X hace Y por razón de Z" solo para ver que el comentario está desactualizado y, de hecho, el método ya no toma el parámetro X? Ocurre todo el tiempo, porque la gente se olvida de actualizar los comentarios. Yo diría que un comentario engañoso es más dañino que ningún comentario. Y, por lo tanto, existe el peligro de comentar en exceso: al crear documentación innecesaria, usted '

Sin embargo, respeto al otro desarrollador de mi equipo y acepto que tal vez él tenga razón y yo esté equivocado. Es por eso que les traigo mi pregunta, compañeros desarrolladores: ¿Es realmente necesario escribir un comentario de javadoc para CADA parámetro? Suponga aquí que el código es interno de mi empresa y que no será consumido por terceros.

Las anotaciones de Javadoc (y, en palabras de Microsoft, XMLDoc) no son comentarios , son documentación .

Los comentarios pueden ser tan escasos como quieras que sean; suponiendo que su código sea legible hasta la mitad, los comentarios ordinarios son meras señales para ayudar a los futuros desarrolladores a comprender / mantener el código que ya han estado mirando durante dos horas.

La documentación representa un contrato entre una unidad de código y sus llamantes. Es parte de la API pública. Siempre suponga que Javadoc / XMLdoc terminará en un archivo de ayuda o en una ventana emergente de autocompletado / intellisense / finalización de código, y será observado por personas que no están examinando las partes internas de su código pero simplemente desean usarlo para algún propósito de los suyos

Los nombres de argumentos / parámetros nunca se explican por sí mismos. Siempre piensas que lo son cuando pasaste el último día trabajando en el código, pero intenta volver a él después de unas vacaciones de 2 semanas y verás cuán inútiles son realmente.

No me malinterpreten: es importante elegir nombres significativos para variables y argumentos. Pero eso es un problema de código, no un problema de documentación. No tome la frase "autodocumentarse" demasiado literalmente; eso se entiende en el contexto de la documentación interna (comentarios), no en la documentación externa (contratos).

Comenta todo o no comentas nada (obviamente comentar todo es una opción mucho mejor). Piense en alguien que usa su código, ya sea revisando su API directamente en su archivo fuente o en un archivo doc generado (es decir, salida de doxygen). Las inconsistencias generalmente conducen a la confusión, lo que lleva al tiempo dedicado a buscar en la fuente para descubrir por qué algo no se comentó, lo que conduce a la pérdida de tiempo que podría haberse evitado si el parámetro hubiera sido comentado en primer lugar.

Recuerde: algo que tiene sentido para usted puede ser interpretado de manera completamente diferente por otra persona, sin importar cuán mundano cree que es (piense en alguien que no es tan fuerte en inglés leyendo e intentando entender su código).

Habiendo dicho todo eso, si el otro desarrollador enfatiza la importancia de documentar todo, entonces se debe poner tanto énfasis (si no más) en mantener la documentación actualizada. Como dijiste, no hay nada peor que tener comentarios desactualizados (igual de malo, si no peor que los documentos omitidos).

Comencemos por suponer que los ciclos de desarrollador son el recurso que estamos tratando de conservar.

Eso significa que los desarrolladores no deberían perder el tiempo documentando parámetros evidentes y valores de retorno, ¿verdad?

Bueno, vamos a desglosarlo.

Si documentamos todo, suponiendo que los comentarios marginales son realmente triviales y no requieren reflexión o investigación, el costo es el tiempo adicional para escribir el comentario y corregir los errores tipográficos.

Si escogemos y elegimos, entonces los costos son:

• Tener y ganar la discusión con los otros desarrolladores de su equipo que piensan que todo debe documentarse.
• Para cada parámetro, determinar si esto debe o no debe documentarse.
• Más discusiones con su equipo cuando alguien tiene una opinión diferente sobre si un parámetro debería haber sido documentado.
• Pasar tiempo buscando el código e investigando cuando un parámetro que se considera autoexplicativo resulta no serlo.

Por lo tanto, me inclinaría a documentar todo. La desventaja es definitiva, pero está contenida.

Si de todos modos está escribiendo Javadoc, también podría escribirlo completamente, incluso incluyendo los parámetros "obvios". Pueden ser obvios para usted o para el otro desarrollador, pero cualquier persona nueva que lo esté mirando se beneficiaría de conocer la intención de cada parámetro.

En cuanto a mantener Javadoc correctamente, debe usar herramientas para su desarrollo que lo ayuden con esto. Eclipse viene a la mente. Por supuesto, si es importante, debe asegurarse de que todos en el equipo hagan su parte para mantener el código, incluidos los comentarios.

No olvide que javadoc se puede hacer visible mientras está separado del código, por ejemplo, la API de Java misma. Al no incluir el javadoc para cada parámetro en un método, está tergiversando el método y cómo podría usarse.

'necesario' es completamente subjetivo. Creo que lo que está preguntando es: "en su situación, debe agregar un comentario javadoc". Sin conocer el alcance o el contexto de su aplicación, ¿cómo podemos saber qué es apropiado para usted?

Si este código público (es decir, código destinado a que otros accedan, como una API), entonces sí, documente cada parámetro. No asumas que el lector conoce el proyecto tanto como tú. Pero por lo demás, depende de usted y su equipo tomar sus propias decisiones.