Regla 0x0203h: Prescindí de comentarios obvios, redundantes o vacíos
Comentarios, documentacion y organizacion de archivos (0x02XX)
0x0203h: Prescindí de comentarios obvios, redundantes o vacíos¶
Enunciado normativo¶
NO DEBE escribirse comentarios que repitan la sintaxis evidente, que sean redundantes con el código ni que estén vacíos (
//,/* */). Todo comentario debe aportar información.
La corrección automática elimina las líneas de comentario vacías.
¿Por qué existe esta regla?¶
El problema¶
Un comentario vacío no solo no aporta: ocupa una línea, ensucia el diff y
hace dudar al lector sobre si falta contenido o si el autor olvidó borrarlo.
Un comentario redundante es peor todavía, porque entrena al lector a ignorar
todos los comentarios, incluidos los que explican decisiones importantes
(0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’).
La regla complementa a 0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’: aquella pide comentar el porqué, esta prohíbe el ruido que se cuela cuando no hay nada que decir.
Consecuencias de violarla¶
| Tipo de consecuencia | Efecto concreto |
|---|---|
| Compilación | Ninguna: los comentarios se descartan (§6.4.9). |
| Legibilidad | El ruido tapa los comentarios útiles. |
| Mantenibilidad | Los comentarios obvios quedan desactualizados con cada cambio. |
| Revisión | El corrector lee líneas sin contenido. |
| Control de versiones | El diff muestra ruido en lugar de cambios significativos. |
Fundamento en el estándar y en la cátedra¶
El estándar define ambas formas de comentario (§6.4.9) sin imponer contenido. La cátedra exige que cada comentario tenga valor informativo, en la línea del principio de claridad de 0x0001h: La claridad y prolijidad son de máxima importancia y de la documentación estructurada de 0x2003h: Todas las funciones deben incluir documentación completa y estructurada.
Alcance y excepciones¶
Aplica a comentarios dentro del código. Los comentarios de cierre en bloques extensos son legítimos cuando cumplen 0x200Dh: Comentarios de cierre explicativos en bloques de control extensos (> 25 líneas). Una línea en blanco dentro de un comentario para separar párrafos tampoco es un comentario vacío. Las cabeceras de archivo con autoría y propósito se rigen por 0x0206h: Validador de presencia de cabecera de documentación obligatoria por archivo.
Ejemplos exhaustivos¶
❌ Contraejemplo 1 — Comentario que repite la sentencia¶
i++; // incrementa i en unoPor qué falla: la línea de código ya dice exactamente eso; el comentario no agrega información y quedará obsoleto si el incremento cambia.
❌ Contraejemplo 2 — Comentario vacío o marcador hueco¶
//
/* */
/* TODO */Por qué falla: no comunican nada; el TODO sin descripción ni responsable no
indica qué falta ni quién debe hacerlo.
✅ Ejemplo conforme 1 — Comentario con contenido técnico¶
// Ajustamos el offset por alineación de 64 bits.
ptr += 8;Justificación: explica el motivo de un desplazamiento que de otro modo parece arbitrario; aporta una restricción que el código no expresa.
✅ Ejemplo conforme 2 — TODO responsable¶
// TODO(equipo): validar el caso de arreglo vacío antes de la entrega.
int total = sumar(valores, cantidad);Justificación: el marcador identifica la tarea pendiente y su contexto; deja de ser ruido y pasa a ser una nota accionable.
⚠️ Casos límite¶
Comentario de cierre corto:
// fin del ifen un bloque de dos líneas es redundante; en uno de 40 líneas, 0x200Dh: Comentarios de cierre explicativos en bloques de control extensos (> 25 líneas) lo exige.Separadores visuales:
// ------------------puede ser aceptable como seccionador si ayuda a navegar un archivo largo.Comentario obsoleto: aunque no sea obvio, si contradice al código debe borrarse o corregirse.
Cómo detectarla¶
| Herramienta | Comando | Señal |
|---|---|---|
gaff | gaff check archivo.c / gaff fix archivo.c | Comentario vacío o TODO sin contenido. |
grep | `grep -nE '^\s*(// | /*)\s*(*/)?\s*$’ archivo.c` |
grep | `grep -nE '//.*(incrementa | asigna |
Checklist de autocontrol¶
¿Algún comentario repite lo que el código ya dice?
¿Quedaron líneas
//o/* */sin contenido?¿Los
TODOexplican qué falta?¿Los comentarios de cierre se justifican por la longitud del bloque?
Reglas relacionadas¶
0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’ — el comentario correcto explica el porqué.
0x0202h: No dejes código comentado (dead code) en los archivos fuente — el código comentado también es ruido.
0x200Dh: Comentarios de cierre explicativos en bloques de control extensos (> 25 líneas) — comentarios de cierre solo en bloques extensos.
0x2003h: Todas las funciones deben incluir documentación completa y estructurada — documentación estructurada de funciones.
0x0206h: Validador de presencia de cabecera de documentación obligatoria por archivo — cabecera de documentación obligatoria por archivo.