Deben los comentarios método / clase aplicarse de manera coherente o sobre una base única necesidad?

Question

Para mantener la coherencia, siempre he aplicado comentarios (en la forma de un JavaDoc) a todos los métodos y clases, incluso si son simples captadores y métodos setters o clases de envoltura muy pequeñas. Pero también estoy tratando de escribir código de auto-documentado que a menudo hace comentarios superfluos; es decir, los comentarios de escritura sólo cuando sea necesario (y antes de hacer eso, tratar de volver a escribir el código de modo que no es necesario el comentario en absoluto). Por lo tanto, estos dos enfoques parecen ser contradictorios entre sí.

Por lo tanto se debe aplicar comentarios que describen un método o una clase de una manera consistente, o debería ser escrito esos comentarios sólo cuando el significado no está completamente claro a partir de la definición?

Answer 1

Una simple prueba de fuego sería comprobar si la clase tiene más comentarios que el código. Si yest entonces significa que su código es demasiado complejo y es difícil de usar para cualquier persona.

Así que lo mejor es escribir código auto explicativo. Además, no hay necesidad de comentarios de escritura para las cosas que son obvias, como las incubadoras y captadores.

Así que me gustaría ir con este tipo de comentarios puede escribir sólo cuando el significado no está completamente claro a partir de la definición.

Answer 2

He utilizado para crear el código para cada método, pero ahora sólo crear la documentación cuando las observaciones añadir un poco más información que el propio código.

Esta es una pregunta sobre un tema similar con un montón de respuestas. Con el avance de código existe la posibilidad de que la actualización de la documentación es "olvidado". En referencia a la pregunta en la documentación enlace mal es peor que no tener la documentación en absoluto.