"Los comentarios son un olor a código" [cerrado]

Un compañero de trabajo mío cree que cualquier uso de comentarios en el código (es decir, no el método de estilo javadoc o los comentarios de clase) es un olor a código . ¿Qué piensas?

Solo si el comentario describe lo que está haciendo el código.

Si quisiera saber qué sucedía en un método o bloque, leería el código. De todos modos, espero que cualquier desarrollador que trabaje en un proyecto determinado esté al menos lo suficientemente familiarizado con el lenguaje de desarrollo para leer lo que está escrito y comprender lo que está haciendo.

En algunos casos de optimización extrema, es posible que esté utilizando técnicas que dificultan que alguien siga lo que está haciendo su código. En estos casos, los comentarios pueden y deben usarse no solo para explicar por qué tiene tales optimizaciones, sino también qué está haciendo el código. Una buena regla general sería que otra persona (o varias otras personas) esté familiarizada con el lenguaje de implementación y el proyecto revisen su código; si no pueden entender tanto el por qué como el cómo, entonces debe comentar tanto el por qué como el por qué. el como.

Sin embargo, lo que no está claro en el código es por qué has hecho algo. Si adopta un enfoque que podría no ser obvio para los demás, debe tener un comentario que explique por qué tomó las decisiones que tomó. Sospecho que es posible que ni siquiera se dé cuenta de que se necesita un comentario hasta después de algo así como una revisión del código, donde la gente quiere saber por qué hizo X en lugar de Y: puede capturar su respuesta en el código para todos los que lo miran en el futuro.

Sin embargo, lo más importante es cambiar sus comentarios cuando cambia su código. Si cambia un algoritmo, asegúrese de actualizar los comentarios indicando por qué utilizó el algoritmo X sobre Y. Los comentarios obsoletos son un olor de código aún mayor.

Esto es particularmente irritante de escuchar en este momento, pasé algún tiempo este fin de semana mirando código muy bien nombrado, muy limpio y sin comentarios que implementa un algoritmo de investigación (uno que no se publica realmente). Estoy familiarizado con él, el inventor que estaba sentado a mi lado y el código fue escrito hace unos años por otra persona. Apenas pudimos seguirlo.

Su compañero de trabajo no tiene suficiente experiencia, obviamente.

Los comentarios deben explicar por qué, no cómo.

HowLos comentarios de tipo generalmente se tratan mejor con refactorización. Personalmente, generalmente evito los comentarios a favor de la refactorización.

Antes de:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

después:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

¡Declaro a tu compañero de trabajo un hereje! ¿Dónde están mis botas heréticas?

Los comentarios obsesivos son malos y un dolor de cabeza de mantenimiento, y los comentarios no reemplazan métodos, clases, variables, etc. bien nombrados. Pero a veces, explicar por qué algo es así puede ser inmensamente valioso para el pobre idiota que tiene que mantener el código en seis meses, particularmente cuando ese pobre idiota termina siendo tú.

Algunos comentarios reales del código en el que estoy trabajando:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

Idealmente, el código debería estar tan bien codificado que debería ser autoexplicativo. En el mundo real, sabemos que el código de muy alta calidad a veces necesita comentarios.

Lo que debe evitar absolutamente es la "redundancia de código de comentario" (comentarios que no agregan nada al código):

i++; // Increment i by 1

Luego, si hay un buen diseño y documentación de código (y mantenido / alineado), comentar es aún menos útil.

Pero en algunas circunstancias, los comentarios pueden ser una buena ayuda en la legibilidad del código:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

No olvides que debes mantener y sincronizar también los comentarios ... ¡los comentarios desactualizados o incorrectos pueden ser un dolor terrible! Y, como regla general, comentar demasiado puede ser un síntoma de mala programación.

Definir categóricamente un método o proceso como un "olor a código" es un "olor a fanatismo". El término se está convirtiendo en el nuevo "considerado dañino".

Recuerde que se supone que todo este tipo de cosas son pautas.

Muchas de las otras respuestas dan buenos consejos sobre cuándo se justifican los comentarios.

Personalmente uso muy pocos comentarios. Explique el propósito de los procesos no obvios y deje la amenaza de muerte ocasional a cualquiera que esté considerando alterar las cosas por su cuenta que requirió semanas de ajuste.

Refactorizar todo hasta que un niño de kinder pueda entender que probablemente no sea un uso eficiente de su tiempo, y que probablemente no funcione tan bien como una versión más concisa.

Los comentarios no afectan el tiempo de ejecución, por lo que el único problema negativo a considerar es el mantenimiento.

En algunos casos, ninguna cantidad de buenos nombres, refactorización, etc. puede reemplazar un comentario. Solo mira este ejemplo del mundo real (el idioma es Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Parece extraño, ¿no? ¿Probablemente un error de copiar-pegar? Llora por una corrección de errores?

Ahora lo mismo con los comentarios:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

El problema principal aquí es el significado del término "olor a código".

Muchas personas (incluido usted, creo) entienden que un olor a código es algo cercano a un error o al menos algo que necesita ser reparado. Quizás pienses en ello como un sinónimo de "antipatrón".

¡Este no es el significado del término!

La metáfora del código olfativo se origina en Wards Wiki , y enfatizan:

Tenga en cuenta que CodeSmell es una pista de que algo podría estar mal, no una certeza. Un idioma perfectamente bueno puede considerarse un CodeSmell porque a menudo se usa mal o porque hay una alternativa más simple que funciona en la mayoría de los casos. Llamar a algo un CodeSmell no es un ataque; es simplemente una señal de que se justifica una mirada más cercana.

Entonces, ¿qué significa que los comentarios son un olor a código: significa que cuando ves un comentario, debes hacer una pausa y pensar: "Hmmm, siento una pista de que algo podría mejorarse". Quizás pueda cambiar el nombre de una variable, realizar el "método de extracción" -refactorización- o quizás el comentario sea realmente la mejor solución.

Eso es lo que significa que los comentarios sean olores de código.

EDITAR: Acabo de toparme con estos dos artículos, lo que lo explica mejor que yo:

• Disculpas en el código
• Para necesitar comentarios

Creo que la regla es bastante simple: imagina a un completo extraño viendo tu código. Probablemente será un extraño para su propio código en 5 años. Intenta minimizar el esfuerzo mental para comprender tu código para este extraño.

Una buena idea para tener los comentarios correctos es comenzar escribiendo comentarios.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Esto le permite extraer métodos fácilmente incluso para deshacerse de los comentarios, ¡
solo deje que el código diga estas cosas ! Vea cómo se reescribe esto (cortar / pegar) de una manera muy agradable:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Para cosas que no se pueden separar, simplemente no extraiga métodos y escriba el código debajo de los comentarios.

Esto es lo que veo como una forma útil de seguir comentando al mínimo, es realmente inútil comentar cada línea ... Solo documente una sola línea si se trata de una inicialización de valor mágico o si tiene sentido.

Si los parámetros se usan demasiado, deberían ser miembros privados de su clase.

Creo que la respuesta es la habitual "Depende". Comentar el código solo para comentar el código es un olor. Comentar el código porque estás usando un algoritmo oscuro que es un orden de magnitud más rápido ahorra al programador de mantenimiento (generalmente yo 6 meses después de que lo escribí) medio día de hurgar en el código para determinar qué está haciendo.

// Dear me in the future. Please, resolve this problem.

o

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

Los comentarios de código definitivamente no son un "olor a código". Esta creencia generalmente proviene del hecho de que los comentarios pueden volverse obsoletos (desactualizados) y pueden ser difíciles de mantener. Sin embargo, tener buenos comentarios que expliquen por qué el código está haciendo algo de cierta manera puede (y generalmente es) importante para el mantenimiento.

Los buenos comentarios facilitan la comprensión de lo que hace el código y, lo que es más importante, por qué lo hace de una manera particular. Los comentarios deben ser leídos por los programadores y deben ser claros y precisos. Un comentario que es difícil de entender o incorrecto no es mucho mejor que no haber hecho ningún comentario.

Agregar comentarios claros y precisos a su código significa que no tiene que depender de la memoria para comprender el "qué" y el "por qué" de una sección de código. Esto es más importante cuando mira ese código más adelante, o alguien más debe mirar su código. Debido a que los comentarios se vuelven parte del contenido textual de su código, deben seguir buenos principios de escritura además de estar claramente escritos.

Para escribir un buen comentario, debe hacer su mejor esfuerzo para documentar el propósito del código (el por qué, no cómo) e indicar el razonamiento y la lógica detrás del código de la manera más clara posible. Idealmente, los comentarios deben escribirse al mismo tiempo que escribe el código. Si espera, probablemente no volverá y los agregará.

Sams Teach Yourself Visual C # 2010 en 24 horas , pp 348-349.

Si el código se ha escrito de una manera particular para evitar un problema presente en una biblioteca (una biblioteca de terceros o una biblioteca que viene con el compilador), entonces tiene sentido comentarlo.
También tiene sentido comentar el código que debe cambiarse en futuras versiones, o cuando se usa una nueva versión de una biblioteca, o cuando se pasa de PHP4 a PHP5, por ejemplo.

Incluso el libro mejor escrito probablemente tenga una introducción y títulos de capítulos. Los comentarios en código bien documentado siguen siendo útiles para describir conceptos de alto nivel y explicar cómo está organizado el código.

De mención honrosa es el antipatrón:

Tengo la impresión de que a veces los ejemplos de licencias de FLOSS se usan con frecuencia en lugar de la documentación del archivo. El GPL / BSDL crea un buen texto de relleno, y después de eso rara vez ve algún otro bloque de comentarios.

No estoy de acuerdo con la idea de que escribir comentarios para explicar el código es malo. Esto ignora por completo el hecho de que el código tiene errores. Puede ser que sea claro cuál es el código hace sin comentarios. Es menos probable que quede claro lo que se supone que debe hacer el código . Sin comentarios, ¿cómo saber si los resultados son incorrectos o si se usan incorrectamente?

Los comentarios deben explicar la intención del código, de modo que si hay un error, alguien que lea los comentarios y el código tenga la posibilidad de encontrarlo.

Generalmente me encuentro escribiendo comentarios en línea antes de escribir el código. De esta manera, queda claro para qué estoy tratando de escribir el código y reduce la pérdida en un algoritmo sin saber realmente lo que está tratando de hacer.

Los comentarios que se hacen porque alguien piensa que está bien tener 700 líneas en un método son un olor.

Los comentarios que están ahí porque sabes que si no pones un comentario, alguien cometerá el mismo error una vez más son un olor.

Comentarios introducidos porque alguna herramienta de análisis de código exige que también sean un olor.

Las personas que nunca harán un comentario o escribirán un poco de ayuda para otros desarrolladores también son un olor. Estoy sorprendido de cuántas personas no escribirán cosas, pero luego se darán la vuelta y reconocerán que no pueden recordar lo que hicieron hace 3 meses. No me gusta escribir documentos, pero me gusta tener que decirle a la gente lo mismo una y otra vez, incluso menos.

Contestaré con una pregunta propia. ¿Puedes encontrar el error en el siguiente código sin comentar?

TL; DR: La próxima persona que mantenga su código podría no ser tan divina como usted.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

Debe mantener un equilibrio entre el código y los comentarios ... Por lo general, trato de agregar algunos comentarios que reanuden un bloque de código. No porque no pueda entender el código (bueno, eso también), sino porque puedo leer más rápido mi propio código y localizar secciones específicas donde sucede lo importante.

De todos modos, mi propio criterio personal es "cuando tenga dudas, comente". Prefiero tener una línea redundante que una línea completamente críptica que no voy a poder entender. Siempre puedo eliminar comentarios en una revisión de código, después de un tiempo (y generalmente lo hago)

Además, los comentarios son bastante útiles agregando "advertencias" como "¡Cuidado! Si el formato de la entrada no es ASCII, ¡este código tendrá que cambiar!"

Al leer esto, recuerdo algo que leí por primera vez (de una lista más larga, preservada al tomar fotocopias) algunas décadas atrás:

Los programadores reales no escriben comentarios: si fue difícil de escribir, debería ser difícil de leer

Un olor bastante mayor me parece.

Creo que los comentarios de código tienen un comienzo muy pobre en la vida. No sé sobre estos días, pero cuando me enseñaron programación en la escuela por primera vez, recibí tareas de la naturaleza de "Escribir un programa que imprima los números del uno al diez en líneas separadas. Asegúrese de comentar su código". Sería marcado si no agregara comentarios porque comentar su código es BUENO.

Pero, ¿qué hay para decir sobre un proceso tan trivial? Entonces terminas escribiendo el clásico

i++; // add one to the "i" counter.

solo para obtener una calificación decente y, si tiene algún problema, formar instantáneamente una opinión muy baja de los comentarios de código.

Los comentarios de código no son BUENOS. A VECES ES NECESARIO, y Thomas Owens en la respuesta principal proporciona una excelente explicación de las situaciones en las que es necesario. Sin embargo, estas situaciones rara vez surgen en tareas de tipo tarea.

En muchos sentidos, agregar un comentario debe considerarse una opción de último recurso, cuando lo que hay que decir no se puede decir claramente en las partes activas del lenguaje de programación. Aunque la denominación de objetos puede quedar obsoleta, varios mecanismos de falta de retroalimentación humana y de la computadora hacen que sea fácil olvidar mantener los comentarios y, en consecuencia, los comentarios se vuelven obsoletos mucho más rápido que el código activo. Por esa razón, donde es posible elegir, cambiar el código para hacerlo más claro siempre debe preferirse a anotar código poco claro con comentarios.

Por supuesto, los comentarios son un olor a código ...

cada programador sabe que todos eventualmente nos volvemos locos debido a la cantidad de trabajo, depuración o simplemente la locura con la que nos encontramos.

"¡Hacer esto!" dice su gerente de proyecto.

Respondes: "No se puede hacer".

Dicen: "Entonces encontraremos a alguien más que lo haga".

Usted dice: "Está bien, bueno, tal vez se pueda hacer".

Y luego pasa la próxima X cantidad de días ... semanas ... meses ... tratando de resolverlo. A lo largo del proceso, intentará y fracasará, e intentará y fracasará. Todos hacemos esto. La verdadera respuesta es que hay dos tipos de programadores, los que comentan y los que no.

1) Aquellos que lo hacen están facilitando su propio trabajo al documentar para referencia futura, comentando rutinas fallidas que no funcionaron (el olor no las elimina después de encontrar la que funciona) o rompiendo el código con comentarios formato para esperemos que sea un poco más fácil de leer o comprender. En serio, no puedo culparlos. Pero al final, se rompen y luego tienes esto: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Los que no lo hacen o fingen ser un superhéroe o viven en una cueva . Simplemente tienen un desprecio temerario por los demás, ellos mismos, y no les importa el código, o qué significado podría tener para más adelante.

Ahora no me malinterpreten ... las variables y funciones autodocumentadas pueden evitar esto por completo ... y confíen en mí , nunca podrán hacer suficiente limpieza de código. Pero la simple verdad es que, siempre que mantenga copias de seguridad, SIEMPRE puede eliminar comentarios.

Yo diría que no usar algunos comentarios en su código es un olor a código. Si bien estoy de acuerdo en que el código debe auto documentarse tanto como sea posible, llegas a un cierto punto en el que vas a ver código que no tiene sentido, independientemente de qué tan bien esté escrito el código. He visto algunos códigos en aplicaciones comerciales donde los comentarios son bastante obligatorios porque:

1. Debe hacer algo caso por caso y no hay una buena lógica para ello.
2. El código probablemente cambiará en un año o dos cuando se cambien las leyes y desee encontrarlo nuevamente rápidamente.
3. Alguien editó el código en el pasado porque no entendía lo que estaba haciendo el código.

Además, las guías de estilo de la compañía pueden decirle que haga algo de cierta manera: si le dicen que debería tener comentarios que describan qué bloques de código está haciendo una función, entonces incluya los comentarios.

Hay una gran diferencia fundamental entre los comentarios y el código: los comentarios son una forma para que las personas comuniquen ideas a otras personas, mientras que el código está destinado principalmente a la computadora. Hay muchos aspectos en el "código" que también son solo para humanos, como nombrar y sangrar. Pero los comentarios están escritos estrictamente para humanos, por humanos.

Por lo tanto, escribir comentarios es tan difícil como cualquier comunicación humana escrita. El escritor debe tener una idea clara de quién es la audiencia y qué tipo de texto necesitarán. ¿Cómo puede saber quién leerá sus comentarios en diez, veinte años? ¿Qué pasa si la persona es de una cultura completamente diferente? Etc. Espero que todos entiendan esto.

Incluso dentro de la pequeña cultura homogénea en la que vivo, es muy difícil comunicar ideas a otras personas. La comunicación humana generalmente falla, excepto por accidente.

Tengo que estar de acuerdo con tu compañero de trabajo. Siempre digo que si os comento mi código, significa que me preocupa que yo no voy a ser capaz de averiguar mi propio código en el futuro. Esto es una mala señal.

La única otra razón por la que agrego comentarios al código es para invocar algo que no parece tener sentido.

Esos comentarios generalmente toman la forma de algo como:

//xxx what the heck is this doing??

o

// removed in version 2.0, but back for 2.1, now I'm taking out again

Los comentarios de código que dan, cuando corresponde, unidades de argumentos de función y retornos, campos de estructura, incluso variables locales pueden ser muy útiles. ¡Recuerda el Orbitador de Marte!

Aquí está mi regla general:

• Escriba el código y almacene un breve resumen del código en un documento separado.
• Deje el código solo durante varios días para trabajar en otra cosa.
• Regresar al código. Si no puede entender de inmediato lo que se supone que debe hacer, agregue el resumen al archivo fuente.

Eduque a su compañero de trabajo sobre la técnica de programación literaria .

No, los comentarios no son un olor a código, son solo una herramienta que se puede abusar.

Ejemplos de buenos comentarios:

// Creo que esto está en cm. ¡Se necesita más investigación!

// Esta es una forma inteligente de hacer X

// Se garantiza que la lista no estará vacía aquí