Regla 0x0206h: Validador de presencia de cabecera de documentación obligatoria por archivo

0x0206h: Validador de presencia de cabecera de documentación obligatoria por archivo¶

Enunciado normativo¶

Todo archivo fuente (.c) o cabecera (.h) DEBE comenzar con un bloque de documentación que indique autoría, cátedra y propósito del módulo, antes de cualquier directiva #include.

¿Por qué existe esta regla?¶

El problema¶

Un archivo suelto no dice quién lo escribió, a qué trabajo pertenece ni qué se proponía resolver. Cuando el código pasa de manos —compañero de equipo, docente que corrige, uno mismo tres meses después— la ausencia de ese encabezado obliga a reconstruir el contexto leyendo el cuerpo entero. La cabecera de documentación concentra en pocas líneas la información estable del archivo, que no se deduce de la implementación.

Consecuencias de violarla¶

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

El estándar C11 no exige encabezados de documentación: es una convención institucional, no una cláusula normativa. La cátedra la adopta para que todo archivo sea autodescriptivo y atribuible, y porque el encabezado es el primer punto donde el estudiante declara la intención del módulo, en línea con 0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’. El comentario inicial no reemplaza la documentación de funciones de 0x2003h: Todas las funciones deben incluir documentación completa y estructurada; la complementa.

Alcance y excepciones¶

Aplica a todos los .c y .h versionados del trabajo, incluidos los archivos de prueba pequeños. No aplica a archivos generados automáticamente por herramientas, siempre que conserven el encabezado que la herramienta emite. El bloque debe ir antes de la primera directiva para que el lector lo vea al abrir el archivo.

Ejemplos exhaustivos¶

❌ Contraejemplo 1 — Archivo que arranca con includes¶

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    printf("hola\n");
    return 0;
}

Por qué falla: no hay autor, ni cátedra, ni propósito. El archivo es anónimo y el docente no puede saber a qué entrega pertenece sin mirar el nombre.

❌ Contraejemplo 2 — Encabezado incompleto o vacío¶

/* lista.c */

Por qué falla: repite el nombre del archivo —dato que ya está en el sistema de archivos— y omite lo que no se deduce: autoría, cátedra y objetivo del módulo. Es un comentario obvio en el sentido de 0x0203h: Prescindí de comentarios obvios, redundantes o vacíos.

✅ Ejemplo conforme 1 — Cabecera de implementación¶

/*
 * Cátedra de Programación 1
 * Archivo: lista.c
 * Autor: <apellido, nombre>
 * Propósito: implementar una lista simplemente enlazada de enteros.
 */

#include "lista.h"

Por qué cumple: encabeza el archivo, declara institución, autor y propósito antes de cualquier inclusión, y la inclusión propia va primero conforme a 0x0205h: En archivos .c la inclusión de la cabecera propia debe figurar en primer lugar.

✅ Ejemplo conforme 2 — Cabecera de archivo de cabecera¶

/*
 * Cátedra de Programación 1
 * Archivo: lista.h
 * Autor: <apellido, nombre>
 * Propósito: interfaz pública del TAD lista.
 */

#ifndef LISTA_H
#define LISTA_H

typedef struct lista lista_t;

#endif

Por qué cumple: el bloque precede a la guarda de inclusión y la guarda usa el nombre del módulo, conforme a 0x5003h: Utilizá guardas de inclusión en todos los archivos de cabecera y 0x010Ch: Auditor de identificadores reservados con doble guion bajo o guion bajo inicial.

⚠️ Casos límite¶

• Archivos de prueba: también llevan encabezado, aunque el propósito sea “casos de prueba de la función X”.

• Fecha y versión: son útiles pero no obligatorias; si se incluyen, que no queden desactualizadas.

• Codificación: evitar acentos dentro del bloque sólo si el flujo no está en UTF-8; los identificadores sí deben ser ASCII (0x0108h: Prohibición de identificadores con caracteres no ASCII (acentos, ñ)).

• Archivo vacío o de una línea: el encabezado sigue siendo obligatorio.

Cómo detectarla¶

Checklist de autocontrol¶

• Todo .c y .h que entrego empieza con el bloque de documentación.

• El bloque dice autoría, cátedra y propósito, no sólo el nombre del archivo.

• El bloque aparece antes de la primera directiva #include.

• Documenté además cada función según 0x2003h: Todas las funciones deben incluir documentación completa y estructurada.

Reglas relacionadas¶

• 0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’ — comentarios que explican la intención.

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

• 0x5005h: Organizá la estructura de tus archivos .c de forma estándar — orden estándar de las secciones del archivo.

• 0x5003h: Utilizá guardas de inclusión en todos los archivos de cabecera — guardas de inclusión en cabeceras.