¿Te preguntas cómo escribir buenos comentarios en programación? Documentar el código es una de las habilidades más infravaloradas —y más importantes— dentro del desarrollo de software.
Algo que hoy tienes claro, en unas semanas puede parecerte completamente desconocido. Y si no lo documentas bien, entender tu propio código (o el de otros) puede convertirse en una pesadilla.
En esta guía completa aprenderás:
- Por qué los comentarios son esenciales
- Cómo escribir comentarios útiles (de verdad)
- Errores comunes que debes evitar
- Ejemplos en múltiples lenguajes
Cómo escribir buenos comentarios en programación
Una de las cosas que más “pereza” da a los programadores es escribir comentarios. Muchos principiantes incluso piensan que no son necesarios.
Error.
Los comentarios bien hechos son una de las diferencias entre código profesional y código amateur.
No se trata de comentar todo, sino de comentar lo importante.
Importancia de los comentarios en un programa
Dentro del mundo de la programación, un comentario es una anotación que explica el código. No afecta a la ejecución del programa, pero sí a su comprensión.
Los comentarios sirven para:
- Entender rápidamente qué hace el código
- Facilitar el mantenimiento
- Permitir que otros desarrolladores trabajen contigo
- Ahorrarte tiempo en el futuro
👉 Piensa en esto: el mayor consumidor de tu código en el futuro… serás tú mismo.
Por eso es clave documentar especialmente:
- Bloques complejos
- Lógica no evidente
- Decisiones técnicas
Ventajas de un buen uso e inconvenientes de un uso pobre
Un buen comentario:
- Reduce el tiempo de mantenimiento
- Facilita la reutilización del código
- Evita errores futuros
Un mal comentario:
- Confunde más que ayuda
- Se queda desactualizado
- Duplica lo que ya dice el código
👉 Regla clave: menos comentarios, pero mejores.
Limitaciones de los comentarios (no sustituyen buen código)
Un error muy común:
usar comentarios para explicar código mal escrito.
Ejemplo incorrecto:
// suma dos números x = a + b;
👉 Eso no aporta nada.
Los comentarios deben explicar:
- El «por qué»
- Decisiones de diseño
- Casos especiales
No el «qué» (eso debería ser obvio en el código).
Reglas y buenas prácticas para escribir comentarios
- Escribe comentarios claros y concisos
- Evita comentarios redundantes
- Mantén los comentarios actualizados
- Usa un estilo consistente en todo el proyecto
- Comenta decisiones importantes, no todo
👉 En equipos, es fundamental seguir una guía de estilo común.
Cuándo debes escribir un comentario
Usa comentarios cuando:
- La lógica no es evidente
- Hay reglas de negocio complejas
- Existen limitaciones técnicas
- Hay “trucos” o soluciones no obvias
Tipos de comentarios
Los comentarios suelen dividirse en dos tipos:
1. Comentarios de línea
Van al final o inicio de una línea.
// Ejemplo de suma entre 2 números
2. Comentarios de bloque
Se usan para explicar partes más largas.
/* Este código permite sumar dos números Pendiente mejorar para decimales */
Usos reales de los comentarios
- Explicar lógica compleja
- Documentar funciones
- Marcar tareas pendientes (TODO)
- Indicar errores conocidos (FIXME)
- Registrar cambios en versiones
Sintaxis de comentarios en distintos lenguajes
C++
/* comentario de varias líneas */ // comentario de línea
C#
// comentario
C
/* comentario */
printf("Hello"); // comentario
CSS
/* comentario */
Java
// línea /* bloque */ /** javadoc */
JavaScript
// línea /* bloque */
Python
# comentario
HTML
Ruby
# línea =begin bloque =end
Visual Basic
' comentario
Matlab
% comentario
Perl
# comentario
Ensamblador
; comentario
Fortran
! comentario
Errores comunes al comentar código
- Comentar todo (ruido innecesario)
- No comentar nada
- Comentarios desactualizados
- Explicar lo obvio
- No seguir un estándar
Ejemplo de buen comentario vs mal comentario
❌ Mal comentario:
// incrementar contador i++;
✅ Buen comentario:
// Incrementamos el contador porque el bucle debe iterar sobre cada elemento procesado previamente i++;
Conclusión
Escribir buenos comentarios es una habilidad clave para cualquier programador.
No se trata de escribir más, sino de escribir mejor.
Un código bien comentado:
- Se entiende rápido
- Se mantiene mejor
- Se reutiliza fácilmente
👉 Recuerda: el mejor código es el que se entiende… incluso meses después.
