El mito de los comentarios en el código: ¿Buenos o malos?

La realidad sobre los comentarios en el desarrollo

El debate sobre si es recomendable o no usar comentarios en el código suele estar marcado por extremos innecesarios. Es fundamental entender que no existen recetas únicas, sino una escala de grises donde el contexto determina la mejor práctica.

Principios clave:

• Código autoexplicativo: El objetivo principal debe ser escribir código que se entienda por sí mismo, evitando la necesidad de explicar acciones triviales.
• El propósito de los comentarios: Deben ser una herramienta para aportar valor, como explicar el por qué de ciertas decisiones técnicas o añadir enlaces a documentación externa.
• La trampa del exceso: Los comentarios también deben mantenerse. Si el código cambia pero el comentario no, se genera una información falsa, lo cual es peligroso para cualquier equipo.

"No hay nada más peligroso que un comentario que mienta."

Alternativas y buenas prácticas

• Los tests como documentación: Los tests funcionan como un excelente registro de comportamiento, ya que describen qué hace la función y qué resultado se espera de ella.
• Evitar la polarización: No clasifiques a un programador como "bueno" o "malo" basándote únicamente en su uso de comentarios. Lo ideal es utilizar todas las herramientas disponibles de forma equilibrada, priorizando siempre la legibilidad y el mantenimiento a largo plazo.