demo técnica · software · legado

Reconstruir la documentación de un software leyendo su código, con examen incluido

Le dimos a un sistema el código fuente de DOOM, cambiamos cuatro cifras a sus espaldas y le pedimos que documentara cómo funciona. Cazó las cuatro: reportó el valor cambiado, con la línea exacta como prueba, mientras la documentación que humanos han escrito de DOOM durante treinta años sigue diciendo lo viejo.

Y para que no te fíes de nuestra palabra, el juego corre aquí mismo, en tu navegador, compilado desde esa misma copia cambiada. Abres una puerta y un cronómetro mide cuánto espera antes de cerrarse: 3 segundos, los que dijo la doc, no los 4,3 de siempre. La prueba deja de leerse y se ejecuta.

El mismo código, corriendo: cronometra el gazapo

No enseñamos el código por un lado y el juego por otro: el motor de aquí abajo está compilado desde el código que documentamos. Arráncalo, abre una puerta con la barra espaciadora y mira el cronómetro de arriba a la derecha. No está pintado: mide el reloj real del motor (35 pasos por segundo) entre que la puerta acaba de abrir y empieza a cerrarse. Cambia entre la copia de siempre y la nuestra con el botón, y verás cambiar la cuenta.

Las cuatro documentaciones: una para cada equipo

Esto es lo que produjo el sistema, y es el objeto de la demo: la misma lectura del código, contada de cuatro formas, cada una en el formato que un equipo distinto ya usa. La técnica para quien mantiene el código, la funcional para negocio y QA, el backlog ágil para un equipo Scrum, y el manual para quien solo juega. La tesis es esa: el mismo conocimiento, en el formato que tu equipo use.

Cada afirmación con número trae su archivo y su línea: pincha cualquiera y abres el código público de id Software en esa línea exacta. Verás el valor de siempre (150, no 105), porque GitHub tiene el código público y aquí documentamos nuestra copia con las cuatro cifras cambiadas. Esa diferencia es justo el experimento, y más abajo te contamos cómo lo montamos.

Cómo lo hacemos: le cambiamos el examen sin avisar

El resultado, con el truco a la vista: mundo, cambio, doc

Como el público de un mago que sí ve el truco: por cada cifra, tres columnas. Lo que dice el mundo (la Doom Wiki y el código público de id Software), lo que cambiamos nosotros en secreto, y lo que la doc generada acabó diciendo. El ojo salta solo: la doc coincide con lo que cambiamos, no con lo que dice el mundo.

El código real, con la línea que lo respalda

No hace falta que sepas C. Pincha una afirmación y salta al fichero real de id Software, con la línea exacta que la respalda señalada en ámbar. Es el mismo código público que enlazan las citas: verás ahí el valor de siempre (150, no 105), porque GitHub tiene la copia pública y nosotros documentamos la nuestra cambiada. Esa diferencia es justo el experimento.

    int             topwait;
    // (keep in case a door going down is reset)
    // when it reaches 0, start going down
    int             topcountdown;
    
} vldoor_t;



#define VDOORSPEED		FRACUNIT*2
#define VDOORWAIT		150

void
EV_VerticalDoor
( line_t*	line,
  mobj_t*	thing );

      case 1:
	// UP
	res = T_MovePlane(door->sector,
			  door->speed,
			  door->topheight,
			  false,1,door->direction);
	
	if (res == pastdest)
	{
	    switch(door->type)
	    {
	      case blazeRaise:
	      case normal:
		door->direction = 0; // wait at top
		door->topcountdown = door->topwait;
		break;

void
P_GunShot
( mobj_t*	mo,
  boolean	accurate )
{
    angle_t	angle;
    int		damage;
	
    damage = 5*(P_Random ()%3+1);
    angle = mo->angle;

    if (!accurate)
	angle += (P_Random()-P_Random())<<18;

    P_LineAttack (mo, angle, MISSILERANGE, bulletslope, damage);
}

// a weapon is found with two clip loads,
// a big item has five clip loads
int	maxammo[NUMAMMO] = {200, 50, 300, 50};
int	clipammo[NUMAMMO] = {10, 4, 20, 1};


//

Resaltado con Shiki en tiempo de build, sobre el fichero C real. La numeración coincide con la del enlace a GitHub.

Llévatelo: el método, no la palabra

Lo que hemos hecho aquí lo puedes hacer tú con cualquier documentación escrita por una IA. Te dejamos las herramientas: la lista de comprobaciones en llano, el corrector con el que puntuamos, y las cuatro documentaciones ya maquetadas, cada una en el formato estándar de su gremio.

Los peros

Lo que esta primera versión todavía no prueba.

Con qué está hecho. La documentación la escribió un modelo de lenguaje leyendo el código: es la parte que redacta y relaciona. Pero quien decide si aprueba o suspende no es el modelo: es un corrector determinista en Python que va a cada línea citada y comprueba el número a mano, sin criterio propio. El modelo propone; el corrector, que no opina, verifica. Las cuatro mutaciones son parches deterministas sobre el código, reproducibles byte a byte, y las 87 citas se resuelven contra el fichero real. El juego es el motor GPL de id Software compilado a WebAssembly con Emscripten; el cronómetro lee el reloj del propio motor (parche nuestro, publicado con el fork), no lo simula.

Licencias y atribución

Esta demo existe porque id Software liberó el código de DOOM. Gracias.

El motor de DOOM es de id Software, publicado bajo licencia GPL-2.0. El código que mostramos y el que compilamos a WebAssembly salen de github.com/id-Software/DOOM, commit a77dfb9, árbol linuxdoom-1.10, vía el port doomgeneric. Nuestra copia con las cuatro mutaciones y el parche del cronómetro se distribuye también bajo GPL-2.0, como pide esa licencia. Los recursos del juego son Freedoom Phase 1 (licencia BSD). DOOM es una marca de id Software; esto no está avalado por id Software ni por ZeniMax.

¿Puedes usar esto? Nuestros textos y análisis de esta página se publican bajo licencia CC BY 4.0: úsalos citando la fuente, Team Banzai (team-banzai.com). El código de DOOM conserva su licencia GPL-2.0.

← Todas las demos técnicas