Diseñar una cabecera: qué exponer y qué esconder

Escribir una cabecera es fácil; diseñarla es una decisión de arquitectura de la que no se vuelve. Todo lo que pongas ahí se convierte en promesa: alguien lo usará, alguien dependerá de su forma exacta y alguien se romperá cuando lo cambies. Lo que no pongas es lo único que te queda libre para reescribir. La pregunta de este nivel no es cómo se escribe un header, sino cómo se decide su frontera — y por qué en C esa frontera solo existe si la construyes deliberadamente.

El criterio: lo necesario para usar, nunca para implementar

Una cabecera contiene exactamente lo que un consumidor necesita para usar el módulo. Nada de lo que hace falta para implementarlo. Esa frase resuelve la mayoría de los casos dudosos, y donde no llegue existe una prueba más afilada: si borro esta línea de la cabecera, ¿deja de compilar algún consumidor legítimo? Si la respuesta es no, la línea sobra, y mientras siga ahí es superficie pública que alguien acabará usando.

/* buffer.h — solo el contrato */
#pragma once
#include <stddef.h>                 /* size_t: lo usa la interfaz */

typedef struct Buffer Buffer;       /* tipo incompleto: opaco */

Buffer *buffer_crear(size_t capacidad);
void    buffer_destruir(Buffer *b);
size_t  buffer_escribir(Buffer *b, const void *datos, size_t n);
size_t  buffer_tamano(const Buffer *b);

/* buffer.c — todo lo demás vive aquí */
#include "buffer.h"
#include <stdlib.h>
#include <string.h>

struct Buffer { unsigned char *datos; size_t usado, cap; };  /* invisible fuera */

static size_t crecer(size_t cap) { return cap ? cap * 2 : 32; }  /* privada */

Fíjate en la desproporción: la cabecera cabe en una pantalla y la implementación puede tener mil líneas. Esa desproporción no es un accidente del ejemplo, es el objetivo. Cuatro decisiones ya están tomadas ahí. La estructura no se ve, así que puedo cambiar sus campos mañana. crecer es static, así que no existe fuera. stdlib.h y string.h los necesita la implementación, no el usuario, y por eso no están en la cabecera. Y el prefijo buffer_ sustituye al espacio de nombres que el lenguaje no tiene.

Lo que se filtra sin que nadie lo note

Exponer una struct completa parece inofensivo porque el compilador no protesta. El precio se cobra después, y en tres monedas distintas.

La primera es la recompilación. Cualquiera que incluya la cabecera depende de la disposición exacta de los campos; tocar uno solo obliga a recompilar todo el árbol de consumidores, incluso los que nunca miran ese campo. La segunda es la ABI: si distribuyes una biblioteca compartida, el tamaño y los desplazamientos de la struct quedan grabados en el código ya compilado de tus usuarios, así que añadir un campo rompe binarios que ni siquiera puedes recompilar. La tercera es la erosión del contrato: en cuanto un campo es accesible, alguien lo leerá, alguien lo escribirá, y en la siguiente versión tu invariante interno ya es una API de facto que no puedes retirar.

Vale la pena detenerse en la tercera, porque es la que decide el destino de un proyecto a largo plazo. Una API no envejece por el código que contiene sino por lo que sus usuarios han llegado a depender: en cuanto algo es observable, alguien construirá encima, y a partir de ese momento cambiarlo rompe programas ajenos con independencia de lo que digan tus comentarios. La regla operativa que se deriva es incómoda pero honesta: todo lo visible acaba siendo contrato, así que la única forma de no prometer algo es no dejarlo ver.

El mismo razonamiento se aplica a cosas que no parecen implementación pero lo son:

flowchart LR
A[Cabecera publica] --> B[Tipos opacos y prototipos]
A --> C[Constantes del contrato]
A --> D[Inclusiones minimas]
E[Archivo de implementacion] --> F[Definicion de las structs]
E --> G[Funciones static]
E --> H[Estado interno del modulo]
style A fill:#a6e3a1,color:#11111b
style E fill:#89b4fa,color:#11111b

Tipos opacos: la frontera que el compilador sí impone

Un tipo opaco es una struct declarada pero no definida en la cabecera. El usuario obtiene un tipo incompleto: puede declarar punteros a él, pasarlos y devolverlos, y no puede hacer absolutamente nada más. No puede leer un campo, no puede reservar uno en la pila, no puede aplicarle sizeof. Y esas prohibiciones no son convención: son errores de compilación. Es la única forma de encapsulamiento de C que el lenguaje hace cumplir, y la razón por la que llevas años usando FILE sin haber visto jamás sus campos.

El precio es real y hay que asumirlo con los ojos abiertos: si el usuario no conoce el tamaño, no puede colocar el objeto en la pila, así que el módulo debe reservarlo, normalmente en el montón, y ofrecer siempre una pareja de funciones de creación y destrucción. Eso descarta el tipo opaco para objetos diminutos y de altísima frecuencia, donde una asignación por instancia sería absurda.

La lista de lo que el usuario deja de poder hacer es, en realidad, la lista de garantías que tú ganas:

#include "buffer.h"

Buffer b;                    /* ERROR: tipo incompleto, tamano desconocido */
size_t t = sizeof(Buffer);   /* ERROR: no se puede medir lo que no se define */
Buffer *p = buffer_crear(64);
p->usado = 0;                /* ERROR: no hay campos visibles */

Cada uno de esos errores es una dependencia que jamás llegará a existir, y por tanto una decisión de implementación que sigues siendo libre de cambiar. Ese es todo el negocio del tipo opaco: comprar libertad futura al precio de rigidez presente.

Cuando ese coste no es aceptable existen dos escapes intermedios. El primero es exponer la struct pero declarar sus campos como internos por convención y documentación —la solución débil, sin garantía alguna—. El segundo es el patrón que usan pthread_mutex_t y compañía: publicar en la cabecera un tipo con el tamaño y la alineación correctos pero sin significado, un bloque de bytes opacos, de modo que el usuario pueda declararlo en la pila mientras la implementación lo reinterpreta por dentro. Compra ubicación en la pila a cambio de congelar el tamaño, que es exactamente la parte de la ABI más cara de cambiar.

Higiene: dependencias y coste de compilación

Cada #include en una cabecera pública es una dependencia que heredan todos tus consumidores, y una arista más en el grafo que decide cuánto se recompila cada vez que tocas algo. Reducirlas es trabajo de diseño, no de limpieza.

Sobre las guardas conviene ser preciso, porque la elección tiene consecuencias. #pragma once no está en el estándar pero lo implementan todos los compiladores relevantes, identifica el archivo por su contenido o su inodo y es inmune a los errores de copiar y pegar. Las guardas clásicas son estrictamente portables y siguen siendo obligatorias en código que deba compilar en cualquier parte, con una condición: el nombre debe derivarse de la ruta completa dentro del proyecto y no del nombre del archivo, porque dos buffer.h en carpetas distintas con la misma guarda producen un fallo espectacular en el que la segunda cabecera simplemente desaparece sin que nadie diga nada.

Y hay una asimetría que resume la sección entera: cambiar un archivo de implementación recompila un objeto; cambiar una cabecera recompila todo su cono de consumidores. La consecuencia práctica es que la estabilidad de una cabecera importa más que su elegancia, y que una cabecera de la que dependen treinta archivos debe estar entre las cosas que menos toques del proyecto. Si no lo está, el problema no es el sistema de compilación: es que ese módulo todavía no ha encontrado su interfaz.

gcc -std=c23 -H -fsyntax-only consumidor.c   # arbol completo de inclusiones
echo '#include "buffer.h"' > /tmp/solo.c && gcc -std=c23 -fsyntax-only /tmp/solo.c
gcc -std=c23 -MMD -MP -c buffer.c            # dependencias para el sistema de compilacion