Regla 0x0201h: Escribí comentarios que expliquen el 'porqué', no el 'qué'

0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’¶

Enunciado normativo¶

DEBE usarse el comentario para registrar la intención, la decisión de diseño o la razón de una construcción no evidente. NO DEBE comentarse lo que el código ya expresa con claridad.

El comentario agrega información que el código no puede contener por sí solo.

¿Por qué existe esta regla?¶

El problema¶

El código dice qué hace; el comentario debe decir por qué lo hace así. Un comentario que repite la sentencia (i++ // incrementa i) no aporta nada y, peor, envejece mal: cuando el código cambia, el comentario queda mintiendo. En cambio, explicar por qué se eligió un bucle inverso o por qué un valor especial es correcto sobrevive a la refactorización.

La regla es una cuestión de señal y ruido: cada comentario redundante compite por la atención del lector y le enseña a saltearlos, incluidos los útiles.

Consecuencias de violarla¶

Fundamento en el estándar y en la cátedra¶

El estándar define las dos formas de comentario (§6.4.9) y no impone su contenido. La cátedra adopta el criterio de intención antes que mecánica, complementario de 0x0203h: Prescindí de comentarios obvios, redundantes o vacíos (que prohíbe los comentarios obvios o vacíos) y de 0x2003h: Todas las funciones deben incluir documentación completa y estructurada (que exige documentación estructurada en funciones).

Alcance y excepciones¶

Aplica a comentarios de línea y de bloque dentro del código. Los bloques de documentación de función siguen la plantilla de 0x2003h: Todas las funciones deben incluir documentación completa y estructurada. Las cabeceras de archivo con autoría y propósito no se consideran redundantes.

Ejemplos exhaustivos¶

❌ Contraejemplo 1 — Comentario que parafrasea¶

// Incrementa i en 1
i++;

Por qué falla: el lector ya sabe leer i++; el comentario no agrega información y ocupará una línea que quedará desactualizada si cambia el incremento.

❌ Contraejemplo 2 — Comentario de lo evidente¶

// Variable para guardar el promedio
double promedio = 0.0;

Por qué falla: describe el nombre, no una decisión; no explica por qué se inicializa en cero ni por qué es double.

✅ Ejemplo conforme 1 — Explicar la decisión¶

// Recorremos del final al principio porque el último byte
// define la paridad del paquete.
for (size_t i = longitud; i-- > 0; )
{
    verificar_byte(datos[i]);
}

Justificación: el comentario registra por qué el orden importa, algo que la sentencia por sí sola no revela.

✅ Ejemplo conforme 2 — Explicar un valor no obvio¶

// El compilador alinea structs a 8 bytes; el relleno explícito
// mantiene el mismo layout entre arquitecturas.
struct registro_t
{
    uint32_t id;
    uint32_t relleno;
    uint64_t marca;
};

Justificación: documenta una decisión de portabilidad que de otro modo parecería un campo inútil.

⚠️ Casos límite¶

• Bucle inverso evidente: si el nombre de la función ya explica el sentido, el comentario puede sobrar; el criterio es la información nueva.

• TODO: es válido si incluye el motivo o un identificador de tarea; un // TODO pelado es ruido (0x0203h: Prescindí de comentarios obvios, redundantes o vacíos).

• Comentario desactualizado: un comentario que contradice al código es peor que ninguno; al modificar, se actualiza o se borra.

Cómo detectarla¶

Checklist de autocontrol¶

• ¿El comentario agrega algo que el código no dice?

• ¿Explica una decisión, un caso raro o una restricción?

• ¿Sigue siendo cierto después de mis cambios?

• ¿Evité describir línea por línea lo evidente?

Reglas relacionadas¶

• 0x0203h: Prescindí de comentarios obvios, redundantes o vacíos — prohibición de comentarios obvios, redundantes o vacíos.

• 0x0202h: No dejes código comentado (dead code) en los archivos fuente — el código comentado tampoco es un comentario legítimo.

• 0x2003h: Todas las funciones deben incluir documentación completa y estructurada — documentación estructurada de funciones.

• 0x200Dh: Comentarios de cierre explicativos en bloques de control extensos (> 25 líneas) — comentarios de cierre solo en bloques extensos.

• 0x0101h: Los identificadores deben ser descriptivos — un buen nombre reduce los comentarios necesarios.