Leer código de verdad

Vas a dedicar la mayor parte de tu carrera a leer código que no escribiste, y nadie te ha enseñado nunca a hacerlo. Es una asimetría absurda: existen miles de cursos sobre cómo escribir y prácticamente ninguno sobre cómo leer. Esta lección corrige eso con un método concreto, un juego de herramientas y tres bases de código canónicas donde los mejores programadores de sistemas vivos dejaron por escrito cómo piensan.

Cómo se entra en un millón de líneas

El error universal es empezar por main y leer hacia abajo. En un fuente grande eso te deposita en la inicialización, que es la parte más aburrida, más histórica y menos representativa de todo el proyecto. El método que funciona invierte el orden y ataca por cuatro frentes.

Primero, los tipos. Las estructuras de datos son la arquitectura; el código es solo lo que hace falta para mantenerlas coherentes. Antes de leer una sola función, localiza las tres o cuatro estructuras centrales y entiende qué representa cada campo. Con eso en la cabeza, el noventa por ciento de las funciones se vuelven obvias antes de leerlas.

Segundo, los tests. Son la única documentación que no puede mentir, porque falla si miente. Un test te dice qué se espera de una función, qué casos límite preocupaban a quien la escribió y cuál es su contrato real —que casi nunca coincide con el que declara el comentario.

Tercero, una sola travesía completa. Elige una operación concreta y síguela de punta a punta, sin desviarte a nada más: una consulta en SQLite desde el texto SQL hasta la página del disco, un comando en redis desde el socket hasta la respuesta, una llamada a read desde la syscall hasta el driver. Una travesía entendida vale más que cincuenta funciones leídas sueltas.

Cuarto, la arqueología. Cuando una línea no tenga sentido, no la mires: pregúntale a git cuándo apareció y por qué.

git clone --filter=blob:none https://github.com/redis/redis   # historia sin blobs
git log -S 'dictRehash' --oneline -- src/dict.c    # el commit que la introdujo
git log --follow -p -- src/ae.c                    # historia completa del fichero
git blame -L 120,160 src/dict.c                    # quien escribio estas lineas
git show <hash>                                    # el mensaje: el porque

git log -S es la herramienta más infravalorada del ecosistema. Busca commits donde el número de apariciones de una cadena cambió, así que te lleva directo al momento en que una función nació o murió, con su mensaje de commit explicando la razón. Una línea absurda casi siempre es la cicatriz de un bug real, y el mensaje del commit es la autopsia.

Las herramientas que lo hacen posible

Navegar a ciegas con grep funciona para diez mil líneas y fracasa para un millón. Lo que necesitas es un índice semántico, que sepa la diferencia entre una definición y una mención en un comentario.

bear -- make                  # genera compile_commands.json para un Makefile
meson setup build             # meson y cmake lo generan solos
ln -s build/compile_commands.json .

Ese fichero es la pieza clave: le dice a clangd con qué banderas se compila cada unidad, y a partir de ahí el servidor de lenguaje entiende el código igual que el compilador. Sin él, en un proyecto con macros de configuración condicional, la mitad del fuente aparecerá desactivada y no encontrarás nada.

La lectura dinámica merece un párrafo propio porque casi nadie la usa para entender código. Compila el proyecto con símbolos de depuración, pon un punto de ruptura en una función central y ejecuta el caso que te interesa: la orden backtrace te entrega, gratis y sin error posible, la cadena exacta de llamadas que te costaría media hora deducir leyendo. Con perf record obtienes lo mismo a escala estadística: qué funciones importan de verdad en la carga real, que es una forma excelente de decidir qué leer primero.

flowchart TD
A[elegir una operacion concreta] --> B[leer los tipos centrales]
B --> C[leer los tests de esa operacion]
C --> D[seguir la travesia completa con gdb]
D --> E[preguntar a git por lo que no encaja]
E --> F[escribir un resumen con tus palabras]
F --> A
style D fill:#89b4fa,color:#11111b
style F fill:#a6e3a1,color:#11111b

Tres maestros

SQLite es probablemente el software más probado del planeta: unas ciento cincuenta mil líneas de código y del orden de mil veces esa cantidad en pruebas, con cobertura MC/DC del cien por cien de las ramas. Se distribuye como un único fichero amalgamado, así que puedes leerlo sin montar nada. Lo que enseña es la disciplina llevada al extremo: assert por todas partes documentando invariantes, comentarios que son verdaderos documentos de diseño arquitectónico, y una estratificación limpísima —analizador, generador de código, máquina virtual, árbol B, paginador, sistema de ficheros virtual— donde cada capa habla solo con la de abajo. Lee src/btree.c para ver un árbol B de producción, y src/vdbe.c para descubrir que SQLite no interpreta SQL: lo compila a bytecode y ejecuta ese bytecode en una máquina virtual propia. Todo lo que hiciste en la lección anterior, a escala industrial.

curl -sO https://sqlite.org/2024/sqlite-amalgamation-3450000.zip
unzip -o sqlite-amalgamation-3450000.zip && cd sqlite-amalgamation-3450000
gcc -std=c23 -g -O0 -DSQLITE_DEBUG shell.c sqlite3.c -o sqlite3 -lm
gdb -q ./sqlite3 -ex 'break sqlite3VdbeExec' -ex run   # el corazon de la VM

redis es la otra escuela: código de una legibilidad casi insultante, escrito para que un humano lo entienda a primera vista. Empieza por src/sds.c, la biblioteca de cadenas cuya idea central cabe en una estructura.

// redis/src/sds.h, esencia: la cabecera va ANTES del puntero que se entrega.
struct sdshdr8 {
    uint8_t       len;      // longitud usada
    uint8_t       alloc;    // capacidad total
    unsigned char flags;    // que variante de cabecera es esta
    char          buf[];    // ESTA direccion es la que recibe el usuario
};

// Del puntero publico a su cabecera: retroceder el tamano de la cabecera.
#define SDS_HDR(T, s) ((struct sdshdr##T *)((s) - sizeof(struct sdshdr##T)))

Léelo dos veces, porque hay tres decisiones densas ahí. Lo que se entrega es buf, así que un sds es una cadena de C perfectamente válida y se puede pasar a printf o a strcmp sin conversión alguna. La longitud está en tiempo constante retrocediendo unos bytes, sin recorrer buscando el terminador nulo. Y el campo flags selecciona entre varias cabeceras de tamaños distintos, de modo que una cadena de treinta bytes paga tres bytes de metadatos y no dieciséis. Sigue después por src/dict.c y su rehash incremental —dos tablas simultáneas, migrando unos pocos cubos por operación para no producir jamás una pausa larga—, y termina en src/ae.c, un bucle de eventos completo en unos pocos cientos de líneas.

El kernel de Linux enseña algo distinto: cómo se organiza el trabajo de miles de personas sobre treinta millones de líneas sin que colapse. El fichero que hay que leer primero es include/linux/list.h.

// Listas intrusivas: el nodo vive DENTRO del objeto, no lo apunta.
struct list_head { struct list_head *next, *prev; };

struct tarea {
    int              prioridad;
    struct list_head enlace;        // el nodo forma parte del objeto
    char             nombre[32];
};

// Del nodo al objeto que lo contiene, en tiempo de compilacion:
#define container_of(ptr, tipo, campo) \
    ((tipo *)((unsigned char *)(ptr) - offsetof(tipo, campo)))

La consecuencia es enorme y se ve enseguida: insertar un objeto en una lista no asigna memoria, porque el nodo ya estaba dentro. Un asignador que puede fallar desaparece de la ruta de inserción, y con él toda una clase de errores en un contexto —el del kernel— donde no siempre puedes dormir esperando memoria. Además, un mismo objeto puede pertenecer a varias listas simultáneamente sin más que llevar varios campos de enlace. En Documentation/ hay decenas de textos escritos por los propios autores, y Documentation/process/ describe una cultura de revisión que ha resultado ser tan importante como el código. Aquí verás además patrones que no existen en el espacio de usuario: RCU para lectura sin cerrojos, likely y unlikely guiando la predicción de saltos, y contadores de referencia por todas partes.

Leer para robar

Leer sin extraer nada es turismo. La lectura productiva termina siempre en una de tres decisiones sobre cada patrón que encuentras: robarlo, archivarlo o descartarlo con razones.

Roba las ideas de representación: la cabecera antes del puntero de sds, los nodos intrusivos del kernel, el bytecode de SQLite. Son transferibles a cualquier proyecto y valen para toda la vida. Archiva las técnicas que hoy no necesitas pero cuya existencia ahora conoces: rehash incremental, RCU, paginación con journal. El valor de archivarlas es que la próxima vez que tengas ese problema sabrás que tiene solución conocida y dónde buscarla.

Y descarta con razones lo que corresponde a restricciones que no son las tuyas. El kernel no puede usar coma flotante en su código ni asumir una pila grande; SQLite evita dependencias externas de forma casi religiosa porque debe compilar en plataformas que no imaginas. Copiar esas decisiones fuera de su contexto es cargar con un coste sin recibir el beneficio, y es el error más común del que acaba de leer un proyecto famoso.