Por qué cambié de opinión sobre los comentarios de código

Recuerdo el día en 2011 cuando encontré un fragmento especialmente complicado en nuestra base de código. Consulté git blame y era mi autoría de hace un año. Ese momento condensó todo lo que aprendí después de dejar la consultoría en 2010. En consultoría escribes código y sigues adelante. En una empresa de producto ese código es tuyo para mantener, ampliar y maldecir a las dos de la mañana cuando la producción falla.

Entré en una fase de fervor por Clean Code de Robert C. Martin. Lo devoré y adopté una regla simple: si hace falta un comentario es porque el código ha fallado en autodescribirse. Empecé a extraer funciones con nombres largos y descriptivos para que el nombre fuera la documentación. El código quedó más limpio, funciones más pequeñas y los nombres más explícitos, pero había algo que no terminaba de encajar.

La lectura de A Philosophy of Software Design de John Ousterhout hizo que mi visión cambiara de nuevo. Ousterhout plantea que los comentarios no son necesariamente fracasos. La información que aportan es distinta y a menudo no puede representarse en código hoy. Los comentarios permiten construir y ocultar abstracciones. Si un usuario tiene que leer la implementación para usar un método, no existe la abstracción y toda la complejidad queda expuesta.

Un ejemplo práctico de esa evolución: un nombre de función puede decir qué hace, pero el comentario explica por qué se eligió ese comportamiento, qué restricciones de negocio existen y qué supuestos se manejan. De pronto entendí que aquellos nombres interminables eran parches para evitar escribir una sola frase clara que explicara el motivo y las condiciones.

La síntesis a la que llegué fue equilibrada. Clean Code acierta en la mayor parte: buen diseño, nombres expresivos y funciones pequeñas son fundamentales. Pero los comentarios no son en sí mismos malos. Los malos comentarios sí lo son. Mi práctica actual es la siguiente: funciones internas cortas requieren comentarios mínimos porque el código habla; funciones complejas necesitan comentarios que expliquen el porqué y el contexto de negocio; las APIs públicas deben llevar documentación obligatoria porque definen la abstracción; los trucos y workarounds complejos deben documentarse para ahorrar horas de confusión.

Hoy, en 2025, con asistentes de codificación basados en IA, los comentarios cobran aún más importancia. Herramientas como GitHub Copilot y asistentes como Claude Code aprovechan los comentarios para entender la intención y generar sugerencias más acertadas. Escribimos comentarios también para máquinas que colaboran con nosotros. Además, el código se lee mucho más de lo que se escribe. Durante mis más de 15 años de experiencia paso gran parte del tiempo comprendiendo y manteniendo código existente, revisando cambios, investigando incidentes y formando a nuevos compañeros. Si leer es diez veces más frecuente que escribir, mejorar la legibilidad tiene un efecto multiplicador en la productividad.

Buenas prácticas sobre comentarios de código

Explica el porqué, no el qué. El código muestra qué hace algo, el comentario debe explicar la intención, el contexto de negocio y los supuestos.

Documenta lo que el código no puede expresar. Contexto, restricciones, decisiones y compensaciones deben ir en comentarios.

Mantén los comentarios cerca del código que describen. La documentación distante se desactualiza con facilidad.

No dupliques el código con el comentario. Comentarios como incrementar contador son ruido y deben eliminarse.

Documenta casos límite y gotchas. Workarounds, supuestos de entrada, condiciones de concurrencia y limitaciones son vitales.

Incluye ejemplos concisos de entrada y salida. Un ejemplo práctico vale más que párrafos abstractos.

Actualiza los comentarios cuando cambies el código. Hazlo parte del proceso de revisión.

Escribe comentarios durante el desarrollo, cuando el contexto está fresco. No los dejes para más tarde.

Utiliza formatos estándar de documentación en tu lenguaje, como JSDoc, Javadoc o docstrings en Python, para facilitar herramientas y asistentes.

En Q2BSTUDIO aplicamos esta filosofía en cada proyecto de software a medida y aplicaciones a medida. Como empresa de desarrollo de software especializada en inteligencia artificial, ciberseguridad y servicios cloud aws y azure entendemos que una buena documentación y comentarios bien pensados aceleran la entrega y el mantenimiento. Integramos prácticas de documentación en nuestros procesos de desarrollo para que los equipos dispongan de contexto útil desde el primer día, ya sea en proyectos de servicios inteligencia de negocio y power bi o en soluciones de agentes IA e ia para empresas.

Si trabajas en soluciones personalizadas, considera que un comentario claro puede ser tan valioso como una buena prueba automatizada. En Q2BSTUDIO combinamos código limpio con documentación precisa para reducir la deuda técnica y facilitar la colaboración. Conoce nuestros servicios de desarrollo de aplicaciones a medida y descubre cómo aplicamos principios de diseño y comentarios efectivos en proyectos reales. También ofrecemos capacidades avanzadas de inteligencia artificial para empresas, integrando agentes IA y soluciones que mejoran la productividad del equipo y la calidad del software.

Conclusión. No hay que eliminar los comentarios por sistema. Escribir código limpio y nombres claros sigue siendo básico, pero los comentarios bien redactados explican aquello que el código no puede. En la era de la IA los comentarios aportan contexto a humanos y máquinas por igual. Tu yo futuro y las herramientas que usas para programar lo agradecerán.