comments - practices - ¿Cuándo son los comentarios "demasiado", y cuándo no son suficientes?
javascript code comments best practices (9)
Hay un debate menor en curso en el que trabajo sobre la eficacia de los comentarios dentro del código. Uno de los clientes potenciales indicó a sus desarrolladores que no usaran comentarios, ya que son demasiado "anticuados", y un par de otros desarrolladores indicaron que nunca usan comentarios porque sienten que todo lo que hacen es desordenar el código.
Siempre me he adherido bastante a la práctica: comento la parte superior de cada archivo con un bloque de comentarios básico, comento cada definición de método / clase / etc, y luego comento cualquier lugar en el código donde creo que podría volver en 6 Meses y pensar para mí, "WTF".
Claramente, esto es subjetivo, pero tengo curiosidad por saber si alguien tiene argumentos o experiencias realmente buenos de una manera u otra.
"Uno de los clientes potenciales instruyó a sus desarrolladores a no usar comentarios porque son demasiado" anticuados ", y un par de otros desarrolladores indicaron que nunca usan comentarios porque sienten que todo lo que hacen es desordenar el código".
Si alguna vez escuché a un desarrollador con el que estaba trabajando hablar así, los corregiría. Si no tuviera el rango necesario para corregirlos, dejaría el trabajo.
El código muy claramente escrito, con buenos identificadores (lo que a veces se denomina "autodocumentación") ilustra bien lo que hace el código. Eso está bien en lo que va. El trabajo de los comentarios es explicar por qué .
De vez en cuando me encuentro con el código que está particionado con tanta elegancia, tiene métodos, campos y nombres de variables tan obvios que todo lo que necesito saber es obvio a partir del código.
En el caso general, solo los grandes gurús del código escriben dicho código. El resto de nosotros improvisamos algo que funciona.
- Si eres un gran gurú del código, no te molestes en manchar tu código divino con comentarios superfluos.
- Si apenas sabe lo que está haciendo, tenga cuidado de documentar sus intentos erróneos para que otros puedan intentar salvar el desastre.
- Si usted es promedio (y la mayoría de nosotros lo somos, por definición) deje algunos consejos para que usted y los demás hagan las cosas más fáciles en el momento del mantenimiento, pero no insulte la inteligencia y el espacio de desperdicios de nadie documentando REALMENTE lo obvio. . Lo ideal es que sus comentarios describan su código a un nivel meta, indicando no lo que está haciendo sino por qué. También cómo, si estás haciendo algo inusual o complicado.
El problema con los comentarios es que tienden a permanecer mucho tiempo después de que el código que fue comentado haya cambiado o incluso haya sido eliminado.
Como regla general, solo comentaría las API públicas y los algoritmos difíciles de entender.
No use comentarios para explicar lo que hizo; para eso es el código, use comentarios para explicar por qué lo hizo.
En toda mi carrera, nunca me he topado con esa maravillosa bestia "código de auto-documentación". Tal vez solo he tenido mala suerte, pero estoy empezando a sospechar que en realidad no existe.
Este tema tiende a discutirse mucho, pero aquí están mis US $ 0.02 sobre el tema:
- Prefiero ver demasiados comentarios que no suficientes. Si falla en algo, siempre puede eliminar comentarios superfluos del código; sin embargo, no se puede derivar un significado de ellos si no hay ninguno para empezar.
- He escuchado a algunos desarrolladores argumentar que otros desarrolladores que "sobre el documento" (las definiciones de esto varían según la persona) su código no son buenos desarrolladores. Si bien decir que está actualizando un contador puede ser una señal de que no sabe lo que está haciendo, tener una guía clara de la lógica de negocios que se encuentra en el medio del método en el que está trabajando puede ser muy útil.
- Si bien hay algunos desarrolladores excelentes por ahí 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 auto documentarse que si hubieran incluido un par comentarios
- No conoce el nivel de habilidad de la siguiente persona que lea 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 un tutorial de Google.
Esto ha sido discutido hasta la muerte.
Solo te indicaré la maravillosa publicación de Jeff Atwood sobre el tema , que te da en el clavo en la cabeza.
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.
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 inmediatamente cuál fue el propósito de ese código.
Me ha ocurrido muchas veces que escribo el código y luego olvido el propósito de eso. Entonces, tengo la costumbre de escribir comentarios antes del código.
Diomidis Spinellis acaba de escribir una bonita columna para la columna IEEE ( citada en su blog ), describiendo el problema y algunas soluciones:
Al comentar, siempre estamos a un par de pulsaciones de tecla lejos del desastre: replanteando la función del código en inglés. Y ahí es cuando empiezan los problemas.