Probablemente has aprendido en algún sitio que se ponen comentarios para documentar el código y explicar los pasos que está haciendo tu programa a otros. Esto no está de todo erróneo, aunque la vida real te puede enseñar otra cosa.

Comentarios no son productivos. No añaden funcionalidad que se podría vender, cuestan tiempo en escribirlos, se quedan obsoleto si cambias el programa y poner comentarios sobra si usas identificadores autoexplicativos. Si quieres saber qué pasa en cada línea del programa, usa un depurador y observa como se cambian las variables. Una de mis frases favoritas es: «Los comentarios ponemos cuando tenemos tiempo.» Desde luego nunca tenemos tiempo. Si no dímelo y te asigno otra tarea.

En conclusión: Olvídate poner comentarios para satisfacer a otros a menos que sea explícitamente requerido. Al final nadie se leerá más que dos líneas de comentario.

La verdadera razón de poner un comentario eres tú. Porque tú eres la primera persona en leer, entender y depurar todo este código que has hecho. Así elige: ¿Poner orden te da pereza y no te importa pasar horas sólo para hacerte entender otra vez lo que ya entendiste hace medio año o, al contrario, es el caos que te da pereza y prefieres que alguien explica para qué todo este código es útil?

No extraña que los programadores que más tendencia tienen a usar identificadores autoexplicativos son también aquellos que más comentarios ponen. Simplemente prefieren pensarse algo una vez y no cada vez que leen algo.

Un trozo de programa escribes una vez, lo modificas diez veces y lo lees cien veces. Si tardas 99 segundos en escribir un comentario que te ahorra un segundo de pensar a la hora de leerlo, entonces todavía sales rentable. Como es probable que nadie más se leerá tu comentario, tampoco cuesta mucho pensar cuántos detalles pones en el comentario: los que a ti te gustaría tener la próxima vez que debes entender esto.

Mis criterios son los siguientes:

  • Si escribo una nueva función, lo primero que hago es apuntarme lo que esta función debería hacer. Esto será el comentario de la cabecera.
  • Lo mismo vale dentro de una función. Primero escribo lo que quiero hacer ahí.
  • Aunque no estoy seguro si borraré una líneas al final, siempre pongo comentarios. Así tengo código bonito desde el primer momento y me ahorro la frustración que debo repasar todo si una vez funciona. (Al final borrar algo no cuesta tanto.)
  • Si hace falta cambiar código de forma temporal, pongo marcadores como «start debug maddin» y «end debug maddin». Está claro que son cambios temporales y como no nombre variables «maddin», es fácil encontrar todos los marcadores temporales. Si cada uno usa una palabra distinta en lugar de «maddin» es incluso posible saber quién ha dejado el marcador ahí.
  • Si una línea de código funciona con misterio pongo un largo comentario no sólo sobre lo que hace esta línea sino porque es mejor que otra forma.
  • A veces pongo incluso un comentario al estilo «me he pasado dos horas para descubrir que el programa se cuelga si llamo la variable a. Ahora se llama b por eso.» Relaja tus sentimientos agresivos cuando lo escribes y te hace sonreír cuando lo vuelves a encontrar. No te cortes incluir alguna palabrota si te relaja. Como mucho tu jefe sale del armario admitiendo que lee tu comentarios.

En fin, la próxima vez que te preguntas si pones un comentario o no, ponlo.