Regla 0x200Dh: Comentarios de cierre explicativos en bloques de control extensos (> 25 líneas)

0x200Dh: Comentarios de cierre explicativos en bloques de control extensos (> 25 líneas)¶

Enunciado normativo¶

DEBE agregarse un comentario en la llave de cierre de toda estructura de control o función cuyo cuerpo supere las 25 líneas, indicando a qué sentencia pertenece el cierre (} // end while (...), } // end funcion).

¿Por qué existe esta regla?¶

El problema¶

Cuando un while o un for ocupa más de una pantalla, la llave de cierre aparece sola, lejos de su apertura. El lector que llega al final ya no recuerda si ese } cierra el if interno, el lazo o la función. Con varios niveles de anidación, un } huérfano es una invitación a insertar código en el bloque equivocado.

El comentario es un ancla visual para los bloques legítimamente extensos; es el complemento del umbral cuantitativo de 0x2014h: Cada función debe caber en una sola idea y en 25 líneas.

Consecuencias de violarla¶

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

El estándar C11 no exige comentarios; las llaves delimitan bloques compuestos que anidan sin ambigüedad para el compilador (§6.8.2). La dificultad es cognitiva, no sintáctica: el lector humano pierde la correspondencia. La cátedra adopta el umbral de 25 líneas, el mismo de 0x2014h: Cada función debe caber en una sola idea y en 25 líneas, para que la señal sea consistente. El comentario debe explicar el porqué o la estructura (0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’), nunca ser un // fin vacío.

Alcance y excepciones¶

Aplica a funciones, while, for, do-while, switch y if de más de 25 líneas. No se exige en bloques cortos: en un if de tres líneas, el comentario es ruido y puede llegar a violar 0x0203h: Prescindí de comentarios obvios, redundantes o vacíos (comentarios obvios).

Excepciones: estructuras de datos inicializadas con tablas largas o macros multilínea generadas; en esos casos el bloque no tiene anidación lógica que aclarar.

Ejemplos exhaustivos¶

❌ Contraejemplo 1 — Cierre huérfano de un lazo largo¶

while (fgets(linea, sizeof(linea), f) != NULL) {
    /* ... 40 líneas de procesamiento con if anidados ... */
        if (linea[0] != '#') {
            agregar(&tabla, linea);
        }
}

Por qué falla: la última llave cierra el while, pero también podría parecer que cierra el if. Después de 40 líneas, el lector no tiene forma de saberlo sin subir a buscar la apertura.

❌ Contraejemplo 2 — Comentario que no aporta¶

for (size_t i = 0; i < n; i++) {
    /* ... 30 líneas ... */
}
// fin

Por qué falla: // fin no dice qué termina. El comentario cumple la forma pero no la función: hay que indicar el for y su condición para que sirva de referencia.

✅ Ejemplo conforme 1 — Comentario de cierre con la condición¶

while (fgets(linea, sizeof(linea), archivo) != NULL) {
    if (linea[0] == '#') {
        continue;
    }

    if (agregar(&tabla, linea) != 0) {
        break;
    }
    /* ... procesamiento extenso ... */
} // end while (fgets ...)

El comentario nombra el lazo y su condición. Cualquier lector ubica inmediatamente el cierre aunque el cuerpo ocupe más de una pantalla.

✅ Ejemplo conforme 2 — Cierre de función y de switch extensos¶

static int procesar_lote(struct lote_t *lote)
{
    int resultado = OK;

    switch (lote->estado) {
    case ESTADO_PENDIENTE:
        /* ... 15 líneas ... */
        break;
    case ESTADO_APROBADO:
        /* ... 12 líneas ... */
        break;
    default:
        resultado = ERROR_ESTADO;
        break;
    } // end switch (lote->estado)

    return resultado;
} // end procesar_lote

Ambos cierres se identifican sin ambigüedad. El comentario final de la función es especialmente útil cuando el cuerpo supera el umbral de 0x2014h: Cada función debe caber en una sola idea y en 25 líneas.

⚠️ Casos límite¶

• Umbral: “más de 25 líneas” se cuenta sobre el cuerpo efectivo, sin comentarios ni líneas en blanco, igual que 0x2014h: Cada función debe caber en una sola idea y en 25 líneas.

• Bloques anidados largos: si dos bloques superan el umbral, cada cierre lleva su comentario para no confundirlos.

Cómo detectarla¶

Checklist de autocontrol¶

• ¿Algún bloque de mi función supera las 25 líneas?

• ¿El cierre de cada bloque extenso indica a qué sentencia pertenece?

• ¿El comentario nombra la condición o el nombre de la función?

Reglas relacionadas¶

• 0x2014h: Cada función debe caber en una sola idea y en 25 líneas — comparte el umbral de 25 líneas con esta regla.

• 0x0203h: Prescindí de comentarios obvios, redundantes o vacíos — un // fin vacío es un comentario redundante.

• 0x2001h: Las funciones deben usar cláusulas de guarda y retornos anticipados para reducir la anidación profunda — menos anidación reduce la necesidad de estos comentarios.