Cómo recuperar el conocimiento del código heredado cuando su autor se marcha

Cuando el autor de un sistema antiguo se marcha, el conocimiento no desaparece en un único instante. Una parte sigue siendo ejecutable en el código fuente. Otra solo pervive en datos de producción, calendarios, hábitos de los operadores e integraciones. Hay conocimientos que nunca se registraron y se han perdido. Una reconstrucción responsable separa estas clases en lugar de fingir que una revisión bastante inteligente del código puede recuperarlo todo.

El objetivo no es explicar cada función. Hay que reconstruir una descripción respaldada por pruebas de lo que hace el sistema, del comportamiento del que depende la empresa y de la incertidumbre que queda. He visto equipos dedicar meses a anotar ramas muertas mientras el contrato real estaba en una entrega nocturna de archivos y en la hoja de cálculo de un contable. Empiece por las pruebas, conserve las contradicciones y obligue al sustituto a demostrar equivalencia donde importa.

El código muestra el mecanismo, no todo el contrato

El código fuente puede revelar el flujo de control, las transformaciones de datos, las reglas de validación, los cálculos, los formatos de mensajes, el acceso a bases de datos y el orden de las llamadas a sistemas externos. A menudo responde preguntas precisas: ¿qué estados detienen la facturación? ¿Cómo se redondean los intereses? ¿Qué campos permiten exportar un registro? ¿Cuándo termina un reintento? Son hechos que merece la pena extraer automáticamente.

El código no puede decir por sí solo si una regla observada es la política actual, una solución provisional obsoleta o un defecto al que los usuarios aprendieron a adaptarse. Una rama que da a la clase de cliente 17 un tratamiento fiscal distinto demuestra que el programa lo hace. No demuestra por qué existe la clase 17, si la excepción sigue siendo legal ni si alguien continúa creando esos clientes. Los comentarios rara vez resuelven la duda. Pueden describir la regla pretendida cuando se escribieron, mientras producción lleva diez años siguiendo una ruta modificada.

Mantenga separados tres conceptos. La implementación es lo que puede ejecutar el código. El comportamiento observado es lo que hizo realmente el sistema desplegado con determinadas entradas y condiciones. La intención empresarial es la razón por la que alguien quiso ese resultado. Una reescritura necesita los dos primeros para mantener el servicio, pero solo las personas, las normas, los contratos o las decisiones tomadas entonces pueden establecer el tercero. Confundir intención e implementación convierte accidentes en requisitos. Ignorar el comportamiento observado rompe consumidores que dependen de esos accidentes.

Esta distinción también corta la discusión habitual sobre si el código es la especificación. El código tiene autoridad sobre sus instrucciones posibles, sujeto a la configuración y las dependencias de ejecución. Las pruebas de producción tienen autoridad sobre qué posibilidades ocurrieron. Ninguno demuestra qué debería pasar el próximo año. Asigne una procedencia a cada afirmación en vez de forzar a un artefacto a responder todas las preguntas.

Trace un mapa de pruebas antes de interpretar

Un mapa de pruebas debe identificar todos los lugares donde se puede observar o limitar el comportamiento del sistema antes de que alguien empiece a escribir documentación narrativa. De lo contrario, el repositorio más fácil se convierte en el centro de la investigación aunque el comportamiento de mayores consecuencias esté fuera.

Separe las pruebas en cuatro grupos:

• Material ejecutable: código, scripts de compilación, JCL, procedimientos almacenados, expresiones de informes, fórmulas de hojas de cálculo, código generado y binarios desplegados.
• Material de ejecución: configuración, indicadores de funciones, definiciones del planificador, variables de entorno, esquemas de bases de datos, colas, formatos de archivo y puntos de acceso.
• Observaciones: registros de peticiones, ejemplos de mensajes, entradas y salidas de procesos por lotes, cambios en bases de datos, informes impresos, incidencias y manuales de operación.
• Registros con autoridad: contratos, manuales de políticas, interpretaciones normativas, solicitudes de cambio aprobadas y decisiones de los responsables del proceso.

Registre el origen, el intervalo de fechas, el entorno, el propietario, la conservación y las carencias conocidas de cada elemento. Un registro de producción sin su versión de configuración puede engañar. Una copia de base de datos sin fecha empresarial puede hacer que la lógica de cierre parezca aleatoria. Un árbol de fuentes sin el binario desplegado no demuestra que el repositorio corresponda a producción.

Use un registro pequeño de pruebas en vez de un documento narrativo enorme:

claim: invoices with hold_code R are not exported
status: observed
evidence:
  - export_job.cob lines 1840-1868
  - nightly output sample 2024-01-16
  - scheduler definition AR_EXPORT
contradiction:
  - runbook says only hold_code L blocks export
owner_needed: accounts receivable
confidence: medium

La contradicción es la parte útil. No la resuelva eligiendo el archivo más reciente o a la persona más segura. Reproduzca la entrada, siga la rama, revise salidas históricas y pregunte al responsable del proceso si la diferencia refleja una norma o una deriva. El registro hace visible el conflicto y da a un revisor posterior algo que puede refutar.

Defina reglas de acceso y tratamiento antes de tocar datos de producción. Las capturas pueden contener credenciales, datos personales, detalles de pago o texto confidencial. Reduzca los campos, censure de forma uniforme, limite el acceso a las pruebas sin tratar y conserve una correspondencia solo cuando la reproducción la necesite. La reconstrucción no justifica crear un segundo archivo sin control de datos sensibles.

La reconstrucción estática empieza en los límites

La forma más rápida de comprender un sistema desconocido es cartografiar lo que cruza sus límites y seguir después hacia dentro. Empezar por el punto de entrada principal sirve para programas pequeños. En un entorno mixto de COBOL, JCL, PL/SQL, código de escritorio y scripts programados quizá no exista un único punto de entrada honesto.

Extraiga primero las interfaces: archivos leídos y escritos, tablas afectadas, mensajes consumidos, rutas HTTP, pantallas de terminal, argumentos de comandos, informes impresos y nombres de tareas programadas. Para cada límite, capture el esquema, emisor o receptor, momento, comportamiento ante errores y ruta de código que lo gestiona. Así obtiene un grafo de dependencias basado en entradas y salidas reales, no en nombres de carpetas.

Gran parte se puede automatizar. Los analizadores construyen grafos de llamadas y linaje de datos. El análisis SQL cartografía lecturas y escrituras. La extracción de constantes encuentra códigos de estado, máscaras de fecha, tipos de registro, nombres de colas y rutas de archivos. La resolución de símbolos entre lenguajes puede conectar un paso JCL con un programa COBOL, este con un procedimiento almacenado y el procedimiento con una tabla. La detección de condiciones duplicadas suele descubrir la misma regla empresarial implementada de forma distinta en varios canales.

Los resultados de búsqueda son pistas, no conclusiones. El envío dinámico, la reflexión, el SQL generado, los miembros de código copiados, las directivas de preprocesador y la configuración de ejecución debilitan un grafo estático. Un grafo de llamadas tampoco dice nada de frecuencia. Una rama ejecutada para cada pedido y otra usada por última vez durante una migración terminada pueden parecer igual de importantes. Marque las conexiones sin resolver y mídalas después.

El historial del repositorio ayuda cuando es historia real y no una importación masiva. Estos comandos ofrecen un rastro compacto para una regla sospechosa:

git log path/to/export.cob
git blame -L 1840,1868 path/to/export.cob
git show <commit>

La salida útil es una secuencia de commits, autores, fechas y rutas cambiadas. Lea la incidencia o solicitud de cambio asociada si existe. No deduzca la intención empresarial del nombre de un autor ni de un mensaje breve. Una línea atribuida a un commit de migración puede ser décadas anterior al repositorio.

La documentación de JCL de IBM trata las instrucciones DD como la asociación entre el nombre lógico de datos de un programa y un conjunto de datos o dispositivo externo. Es un buen ejemplo de la importancia de los límites: leer solo el SELECT de COBOL no indica qué conjunto de datos de producción llega a ese lugar. Necesita el JCL desplegado, las convenciones del catálogo, los parámetros del planificador y, a veces, el procedimiento del operador para reconstruir la entrada real.

El tráfico de producción revela el contrato efectivo

Las interacciones registradas en producción muestran qué entradas se produjeron y qué salidas recibieron los consumidores, incluido el comportamiento que nadie pensó documentar. Son la mejor base práctica para un banco de paridad, siempre que entienda qué excluye la grabación.

Capture en límites estables. Para un servicio, registre peticiones normalizadas, respuestas, códigos de estado y efectos duraderos. Para procesos por lotes, conserve archivos de entrada, parámetros, filas iniciales relevantes, archivos de salida, informes y diferencias en base de datos. Para una aplicación de escritorio, registre comandos o acciones del usuario en el límite del dominio en lugar de píxeles de vídeo, salvo que el diseño de la pantalla sea contractual. Sustituya valores variables como marcas de tiempo e identificadores generados por reglas de comparación, no por un borrado arbitrario.

Un caso útil de reproducción contiene contexto suficiente para explicar una diferencia:

{"case_id":"export-00418","business_date":"2024-01-31","input_ref":"sha256:...","config_ref":"sha256:...","expected":{"records":418,"rejects":3,"total_minor_units":9021441}}

Los hashes vinculan el caso a pruebas inmutables sin poner un archivo completo de cliente en la definición. El objeto esperado compara resultados empresariales en vez de igualdad de bytes. Si el orden de columnas o el relleno de ancho fijo importa a un consumidor, añádalo por separado como comprobación de formato.

El muestreo necesita intención. El tráfico aleatorio cubre rutas comunes, pero omite el cierre trimestral, años bisiestos, ajustes retroactivos, archivos vacíos, longitudes máximas, reversiones y recuperaciones de error poco frecuentes. Cree estratos alrededor de eventos empresariales y condiciones de ramas. Mantenga casos normales porque revelan patrones de volumen y añada después límites obtenidos del análisis y del historial de incidencias. Nunca afirme una cobertura completa solo porque una captura grande se reproduce sin fallos.

El tráfico también contiene defectos heredados. Si el servicio antiguo devuelve un estado incorrecto que un proceso posterior interpreta correctamente, cambiarlo durante la reescritura puede provocar una caída. Conserve primero el comportamiento, márquelo como defecto conocido y programe un cambio coordinado. La paridad es un control de migración, no una aprobación de cada resultado heredado.

Michael Feathers describe en Working Effectively with Legacy Code las pruebas de caracterización como pruebas que registran lo que hace actualmente el software, no lo que alguien cree que debería hacer. El principio encaja con la reconstrucción, pero requiere una salvedad: una batería superada solo demuestra equivalencia para las observaciones elegidas. No puede recuperar casos ausentes de la muestra ni demostrar que el resultado actual sea legal.

El tiempo, el estado y los operadores crean comportamiento oculto

Los sistemas con procesos programados, estado acumulado u operaciones manuales no se pueden reconstruir a partir de pares aislados de petición y respuesta. Su salida depende de cuándo se ejecuta una tarea, qué ocurrió antes y qué intervención cambió el estado.

El cierre mensual es la trampa habitual. Un cálculo puede consultar un calendario empresarial, procesar llegadas tardías, reabrir un periodo anterior y crear asientos de compensación en un paso posterior. Reproducir el último archivo de entrada contra una base limpia da un resultado plausible que sigue siendo incorrecto. Conserve una secuencia de instantáneas de estado y eventos a través del límite, incluidas zonas horarias del planificador y tablas de festivos. Pruebe un periodo cerrado, uno reabierto y una ejecución fallida reanudada después de escrituras parciales.

Los reintentos merecen un modelo propio. Puede que una tarea sea técnicamente segura al repetirla solo porque un operador elimina antes un archivo marcador. Un consumidor de cola puede deduplicar dentro de un proceso y duplicar trabajo tras reiniciarse. Un procedimiento almacenado puede confirmar cada mil filas y dejar un prefijo completo tras fallar. El análisis estático encuentra confirmaciones y marcadores. Solo el historial y la reproducción controlada revelan cómo funciona en conjunto la recuperación.

Los operadores forman parte del sistema desplegado aunque nadie pretendiera esa arquitectura. Entrevíste los con artefactos concretos. Pídales que recorran la última ejecución fallida, muestren el comando utilizado, expliquen qué salida despertó sospechas e identifiquen a quién llaman antes de repetirla. Las preguntas generales como «¿Cómo funciona la conciliación?» invitan a explicaciones ordenadas. La cronología de un incidente real revela comprobaciones y excepciones.

Convierta esas intervenciones en estados explícitos del flujo de trabajo. Registre condiciones previas, comando o acción en pantalla, autorización, prueba esperada y reversión. Si el sustituto automatiza la acción, preserve el punto de decisión y el rastro de auditoría en vez de esconderlos en un bucle de reintento. Si un juicio no se puede automatizar con seguridad, manténgalo como tarea humana identificada y con suficiente contexto para un operador nuevo.

El comportamiento del reloj requiere pruebas directas. Identifique conversiones de hora local, cambios de horario, fechas empresariales, relojes de servidores de bases de datos y archivos cuyas fechas salen del nombre y no del contenido. Congele el reloj en pruebas cuando sea posible. En el banco de paridad, normalice las marcas visibles solo después de comprobar que orden, cortes y fechas contables siguen coincidiendo.

Las excepciones raras implican más riesgo que las rutas comunes

Las ramas menos frecuentes suelen codificar las mayores consecuencias financieras, jurídicas u operativas. El análisis estático las encuentra, pero la clasificación de pruebas determina si son requisitos activos, salvaguardas latentes o restos inalcanzables.

Empiece con condiciones ligadas a importes grandes, acciones privilegiadas, jurisdicción, estado del cliente, anulaciones manuales, borrado de datos o mensajes externos irreversibles. Compare esas ramas con recuentos de producción y normas. Un recuento cero significa «no observado en esta ventana», no «sin uso». Las reglas estacionales y los procedimientos de emergencia pueden ser válidos aunque ninguna traza reciente los incluya.

Un fallo conocido empieza con una rama aparentemente muerta. El equipo no observa ejecuciones en noventa días, la elimina y supera todas las reproducciones. Seis meses después llega un ajuste anual con un tipo de transacción creado por un parámetro del planificador. La rama antigua habría dividido el importe entre dos libros y habría impreso un informe de excepción. El sistema nuevo acepta el registro por su ruta predeterminada, por lo que los totales cuadran aunque la asignación sea incorrecta. Nadie lo detecta hasta conciliar con un extracto externo.

La decisión correcta habría unido cuatro hechos: la rama existía, el planificador aún podía producir el tipo, un manual anual mencionaba el informe y la ventana observada no incluía el evento anual. Ninguno demuestra por sí solo una necesidad vigente. Juntos justifican una prueba dirigida y una pregunta a finanzas.

No responda documentando cada rama con el mismo esfuerzo. La recomendación es popular porque produce progreso visible y porcentajes ordenados. Es errónea porque mil funciones de poco impacto pueden ocultar una regla de liquidación latente. Priorice por impacto, alcanzabilidad, conflicto de pruebas y reversibilidad. Deje las referencias generadas para el código rutinario y concentre la atención humana donde una inferencia equivocada sería cara de deshacer.

El borrado necesita un criterio explícito. Retire una ruta solo si puede demostrar que es inalcanzable con la configuración desplegada, que una decisión con autoridad la declaró obsoleta o que está contenida de forma segura con supervisión y reversión. En otro caso, consérvela en el primer sustituto o aíslela con un disparador claro. La incertidumbre debe influir en el diseño de la migración, no desaparecer de la documentación.

Parte del conocimiento se ha perdido de verdad

Ningún método puede recuperar una razón sin documentar que no dejó una traza diferenciada. Si dos motivos empresariales habrían producido el mismo código, datos y salidas, las pruebas no pueden decir cuál tenía el autor. Afirmar lo contrario es inventar.

El conocimiento perdido suele incluir alternativas rechazadas, límites políticos, promesas verbales, interpretación de normas ambiguas y el motivo de un umbral concreto. Puede recuperar exactamente el umbral y encontrar cada transacción afectada sin saber si procedía de una ley, del apetito de riesgo, de un límite de proveedor o de una concesión temporal. Esa diferencia importa cuando alguien propone cambiarlo.

Clasifique las incógnitas en vez de ocultarlas con prosa segura:

• Recuperable: existen pruebas que aún no se han conectado, como una columna inexplicada que rellena una tarea conocida.
• Comprobable: la intención es desconocida, pero el comportamiento actual se puede medir y preservar.
• Decidible: las pruebas no resuelven la cuestión, así que un responsable debe elegir la política futura.
• Irrelevante: la respuesta no cambiaría el comportamiento, el riesgo, la operación ni el diseño.

Para una incógnita decidible, escriba un registro con el comportamiento observado, las interpretaciones plausibles, los casos afectados, el responsable, la regla elegida y su tratamiento migratorio. No etiquete la nueva elección como conocimiento recuperado. Así un auditor o ingeniero posterior no confundirá una decisión nueva con un hecho histórico.

La ausencia también limita la confianza. Los registros pueden omitir los datos rechazados. Las instantáneas de base pueden mostrar el estado final sin los efectos intermedios. Las incidencias favorecen fallos frente al trabajo rutinario correcto. Las entrevistas reflejan memoria e incentivos actuales. Declare estos puntos ciegos junto a las conclusiones que debilitan. Una puntuación sin explicación de las pruebas ausentes es decorativa.

Hay una regla útil para detenerse. Continúe mientras una nueva prueba pueda cambiar una decisión importante de implementación o política. Termine cuando la incertidumbre restante tenga responsable y plan de contención y no exista una vía razonable hacia mejores pruebas. La arqueología consume cualquier presupuesto si nadie define qué decisión debe apoyar la excavación.

Convierta los hallazgos en una especificación ejecutable

La especificación reconstruida debe permitir a los ingenieros construir y cuestionar un sustituto, no solo admirar un diagrama. Combine contratos legibles por máquina con prosa breve para decisiones e incertidumbre.

Para cada capacidad empresarial, registre entradas, salidas, transiciones de estado, invariantes, errores, tiempos, permisos, dependencias externas y referencias de las pruebas. Añada ejemplos de casos de producción saneados. Ponga reglas aritméticas en pruebas ejecutables, formatos de archivo en esquemas, conducta de API en casos de contrato y decisiones de operadores en definiciones de flujo. La prosa debe explicar por qué existe cada comprobación y dónde puede estar incompleta.

Organice la especificación en torno a eventos empresariales, no módulos antiguos. Un evento «contabilizar pago» puede cruzar una pantalla, un programa COBOL, un procedimiento almacenado, una extracción nocturna y un informe. Copiar el árbol de carpetas antiguo oculta la cadena. Una vista por eventos hace visibles responsabilidad y paridad a través de los límites técnicos.

Asigne a cada afirmación uno de cuatro destinos: preservar, cambiar de forma intencionada, retirar o investigar. Un cambio necesita responsable y plan de despliegue para los consumidores afectados. Una retirada necesita pruebas de alcanzabilidad. Una investigación necesita una pregunta acotada y una fecha ligada a una decisión de construcción. Así las dudas no permanecen eternamente en comentarios.

Revise con ejemplos adversos, no con diapositivas. Pida al operador que encuentre una ruta de recuperación ausente. Pida a finanzas una transacción que cruce el límite de un periodo. Pregunte al responsable de integración qué registros mal formados sigue enviando. Pase los casos por el sistema antiguo cuando sea seguro, añada las observaciones al registro y actualice los casos ejecutables. Las personas recuerdan excepciones cuando reaccionan a entradas y salidas concretas.

Mantenga la procedencia junto a las pruebas. Cuando falla una comprobación de paridad, el ingeniero debe ver si el valor esperado salió del análisis, de una traza, de una norma o de una decisión. La respuesta cambia: reparar el sustituto, cuestionar la muestra o escalar un conflicto de política. Un valor esperado desnudo oculta esa elección.

Un sustituto gana confianza con paridad medida

La reconstrucción tiene éxito cuando el nuevo sistema puede procesar trabajo registrado representativo, producir resultados acordados, exponer diferencias intencionadas y operar durante fallos. Un documento por sí solo no puede establecerlo.

Ejecute las implementaciones antigua y nueva con los mismos casos saneados. Compare salidas del dominio, cambios duraderos de estado, mensajes externos, clases de error y pruebas para operadores. Normalice solo valores cuya irrelevancia esté demostrada. Clasifique cada diferencia como defecto del sustituto, cambio aceptado, indeterminación que debe controlarse o ambigüedad recién descubierta. No debilite una comprobación para que el panel aparezca verde.

Ordene la migración por límites observables. Un punto de servicio sustituido gradualmente es fácil de comparar si las peticiones y efectos se pueden reflejar con seguridad. Una cadena por lotes quizá necesite salidas paralelas y conciliación antes del cambio. Un flujo de escritorio puede mover primero su cálculo tras un servicio compartido conservando la interfaz antigua. La arquitectura puede cambiar mucho mientras los casos de paridad mantienen estable el comportamiento empresarial.

Aquí encajan el análisis del repositorio completo y la verificación con tráfico. CodeHero lee en paralelo árboles heredados de varios lenguajes, los reescribe en Go, Rust, TypeScript y Postgres, y comprueba la conducta con un banco de paridad frente a tráfico de producción registrado. Cada proyecto se entrega en menos de 30 días. La afirmación útil no es que la automatización redescubra cada intención perdida. Puede recuperar mecanismos a escala y someter afirmaciones de comportamiento a comparaciones repetibles.

Conserve el registro de incertidumbre después del cambio. Aparecerán pruebas cuando se ejecuten eventos estacionales, consumidores olvidados llamen a un punto y los operadores hallen viejas excepciones. Supervise las suposiciones de mayor consecuencia. Si surge un caso desconocido, envíelo al responsable del registro de decisión en vez de hacer que un ingeniero adivine durante una incidencia.

No puede entrevistar a un autor ausente a través de su código. Puede construir algo mejor: una descripción rastreable de lo que permite el código, lo que ha demostrado producción, lo que decide ahora la empresa y lo que nadie puede saber con honestidad. Esa descripción se puede probar y revisar, y es mucho más difícil perderla con la próxima salida.