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.