¿Cuándo son los comentarios "demasiado" y cuándo no son suficientes?

Question

Hay un debate menor en curso donde trabajo sobre la eficacia de los comentarios dentro del código. Uno de los líderes instruyó a sus desarrolladores para que no usen los comentarios ya que están demasiado "anticuados", y un par de desarrolladores más indicaron que nunca usan comentarios porque sienten que todo lo que hacen es desordenar el código.

Siempre me he adherido a la práctica de comentar el principio de cada archivo con un bloque de comentario básico, comentar cada método/clase/etc definición, y luego comentar cualquier lugar en el código donde creo que podría volver en 6 meses y pensar para mí mismo, "WTF".

Claramente, esto es subjetivo, pero tengo curiosidad por saber si alguien tiene argumentos o experiencias realmente buenos para una forma u otra.

Answer 1

Esto se ha discutido hasta la muerte.

Simplemente te indicaré Jeff Atwood's wonderful post on the subject, que da en el clavo justo en la cabeza.

Answer 2

De vez en cuando me encuentro con un código que está tan elegantemente particionado, tiene métodos de campo, variables y nombres tan convincentes que todo lo que necesito saber es obvio desde el código.

En el caso general, sólo es realmente grandes gurús escribe código como código. El resto de nosotros improvisamos algo que funciona.

• Si eres un gran gurú del código, no te molestes en ensuciar tu código divino con comentarios superfluos.
• Si apenas sabe lo que está haciendo, tenga cuidado para documentar sus intentos torpes para que otros puedan tratar de salvar el desorden.
• Si usted es la media (y la mayoría de nosotros estamos, más o menos por definición) y luego dejar algunos consejos en los comentarios para sí mismo y otros para facilitar las cosas a la hora del mantenimiento, pero no insultes a nadie espacio de la inteligencia y de los residuos mediante la documentación el REALMENTE obvio. Idealmente, sus comentarios deberían describir su código en un meta-nivel, indicando no lo que está haciendo sino por qué. También cómo, si estás haciendo algo inusual o complicado.

Answer 3

El problema con los comentarios es que tienden a permanecer mucho tiempo después de que el código que se comentó ha cambiado o incluso se ha eliminado.

Como regla general sólo había comentar API pública y difícil de entender algoritmos.

No utilice los comentarios para explicar lo que hizo, para eso sirve el código, use los comentarios para explicar por qué lo hizo.

Answer 4

Se debe escribir un comentario antes del código o antes de la función para que la próxima vez que vea la función pueda saber de inmediato cuál era el propósito de ese código.
Me ha pasado muchas veces que escribo el código y luego olvido el propósito de eso. entonces, tengo la costumbre de escribir un comentario antes del código.

Answer 5

Lo que me gustaría ver en los comentarios es una explicación de por qué un método que es obvio y mucho más simple que el método utilizado en el código no funciona.

Answer 6

En toda mi carrera, nunca he llegado a través de ese maravilloso bestia "código de auto-documentado". Quizás he tenido mala suerte, pero estoy empezando a sospechar que en realidad no existe.

Answer 7

"Uno de los clientes potenciales instruyó a sus desarrolladores para que no usen los comentarios ya que son demasiado anticuados, y otros desarrolladores indicaron que nunca usan comentarios porque sienten que todo lo que hacen es complicar el código".

Si alguna vez escuché a un desarrollador que estaba trabajando con una conversación como esta, los corregiría. Si no tuviera el rango necesario para corregirlos, dejaría el trabajo.

El código muy claro, con buenos identificadores -algo que a veces se conoce como 'auto-documentación' - hace un buen trabajo al ilustrar lo que el código está haciendo. Eso está bien hasta donde llega. El trabajo de los comentarios es explicar por qué.

Answer 8

En este tema tiende a ser discutido mucho, pero aquí están mis US $ 0.02 sobre el tema:

1. Prefiero ver demasiados comentarios que no es suficiente. Si falla en algo, siempre puede eliminar comentarios superfluos del código; sin embargo, no puedes derivar significado de ellos si no hay ninguno allí para empezar.
2. He oído a algunos desarrolladores argumentar que otros desarrolladores que "sobre el documento" (las definiciones de esto varían por persona) su código no son buenos desarrolladores. Aunque decir que estás actualizando un contador puede ser una señal de que no sabes lo que estás haciendo, tener una guía clara sobre la lógica de negocios que se encuentra allí en medio del método en el que trabajas puede ser muy útil.
3. Si bien hay algunos desarrolladores excelentes que pueden escribir código extremadamente claro que no requiere comentarios, la mayoría de los desarrolladores no son tan buenos o pasan más tiempo escribiendo el código para documentarse a sí mismos de lo que lo harían si hubieran solo incluido un par de comentarios.
4. No sabe el nivel de habilidad de la siguiente persona para leer su código y si las construcciones de lenguaje que está utilizando pueden ser confusas, generalmente es una buena idea incluir un comentario que alguien pueda usar para buscar en Google.

Answer 9

Diomidis Spinellis acaba de escribir un buen columna para la columna IEEE (quoted on his blog), describiendo el problema y algunas soluciones:

Al comentar, siempre estamos un par de pulsaciones de teclas lejos del desastre: restableciendo la función del código en inglés. Y ahí es cuando comienzan los problemas .