Como documentar um sistema legado que ninguém documentou

Por que documentar antes de mexer

Um sistema sem documentação não é um sistema sem regras. As regras estão todas lá — no código, nos triggers do banco, na ordem em que as telas são preenchidas, na planilha que o financeiro confere todo fim de mês. Elas só não estão escritas num lugar onde alguém consiga ler.

Na NasteSoft, toda migração de sistemas legados segue a mesma ordem: entender como o sistema funciona, documentar, e só então escrever código. Não é burocracia. É que o sistema novo só pode ser tão correto quanto o entendimento que se tem do antigo. Pular essa etapa — por exemplo, usando um conversor que traduz o código sem que ninguém o entenda — é o que leva aos problemas que descrevemos em por que não usamos conversor automático de código.

E mesmo sem migração no horizonte, a documentação de software legado reduz um risco que toda empresa com sistema antigo tem: depender da memória de uma ou duas pessoas.

As fontes: onde o conhecimento está escondido

Engenharia reversa de sistema não é só ler código. O código diz o que o programa pode fazer; as outras fontes dizem o que ele faz na operação real. Usamos todas.

Código-fonte

O ponto de partida óbvio, mas com atalhos que pouca gente usa. Em Delphi, boa parte do SQL não está nos arquivos .pas: está nos .dfm, na propriedade SQL dos componentes de consulta, junto com eventos ligados a cada componente. Em VB6, o arquivo .vbp lista as referências e os controles ActiveX que o projeto usa, e os .frm guardam as propriedades das telas. Uma busca por SELECT, UPDATE, INSERT e DELETE em todo o fonte já produz um mapa inicial de quais telas tocam quais tabelas. No Delphi, no VB6 e no .NET Framework as armadilhas mudam, mas o princípio é o mesmo.

Banco de dados

Em muito sistema antigo, o banco é a parte mais bem conservada — e a que mais esconde regra. Três coisas a levantar: o dicionário de dados (tabelas, colunas, tipos, chaves, o que cada campo realmente guarda), os triggers (que alteram dados sem que nenhuma tela mostre) e as procedures e funções (onde costumam morar os cálculos mais antigos). Um primeiro levantamento cabe numa consulta:

-- SQL Server: onde há lógica dentro do banco
SELECT o.type_desc, o.name, OBJECT_NAME(o.parent_object_id) AS tabela_pai
FROM sys.objects o
WHERE o.type IN ('TR', 'P', 'FN', 'IF', 'TF', 'V')
ORDER BY o.type_desc, o.name;

-- Firebird: triggers criados pelo usuário
SELECT RDB$TRIGGER_NAME, RDB$RELATION_NAME
FROM RDB$TRIGGERS
WHERE COALESCE(RDB$SYSTEM_FLAG, 0) = 0;

Os dados também falam. A data do último registro em cada tabela mostra o que ainda é usado; a distribuição de valores de um campo de status revela estados que o código nem trata mais; um campo de observação usado para guardar três informações diferentes é uma regra informal esperando para ser descoberta.

Telas em uso, relatórios e logs

Sentar ao lado de quem opera e observar o trabalho real vale mais que qualquer diagrama. Em uma manhã aparecem os atalhos, os campos que todo mundo ignora, a tela que só é aberta no fechamento do mês. Relatórios são outra mina: cada relatório impresso é um cálculo que alguém considera oficial. E logs — de aplicação, de banco, de acesso — mostram frequência de uso e erros recorrentes que viraram "normais".

Entrevistas e planilhas paralelas

As entrevistas com quem opera não servem para perguntar "como o sistema funciona" — ninguém sabe responder isso. Servem para perguntar sobre casos: "e quando o cliente paga metade?", "o que acontece se o pedido for cancelado depois de faturado?". E sempre vale perguntar: "tem alguma planilha que vocês usam junto com o sistema?". Quase sempre tem. A planilha paralela é o sistema dizendo, por escrito, o que ele não faz — e que provavelmente precisa fazer na versão nova.

O que documentar (e o que deixar de fora)

A tentação é documentar tudo, e isso produz um documento enorme que ninguém lê. O foco é no que o sistema novo precisa reproduzir ou decidir conscientemente não reproduzir:

• Regras de negócio e cálculos, sempre com exemplo numérico. "Calcula o desconto" não é documentação; "pedido à vista de R$ 6.000,00 recebe R$ 300,00 de desconto" é.
• Fluxos. A sequência real de um pedido, de uma nota, de uma ordem de serviço — com os estados possíveis e quem pode mudar cada um.
• Integrações. Arquivos exportados para a contabilidade, troca com banco, emissão fiscal, importação de planilha, o outro sistema que lê direto do banco. Integração esquecida é a causa clássica de problema no dia seguinte à virada.
• Permissões. Quem pode fazer o quê, inclusive as regras que estão no código como if usuario = 'MARIA'.
• Casos de borda. Valor zero, cliente sem cadastro completo, mês com feriado, devolução parcial. É onde mora a maior parte das regras que ninguém lembra.
• O que está morto. Telas sem uso, rotinas que nunca são chamadas, campos sempre vazios. Documentar o que não será migrado reduz escopo e evita discussão depois.

O formato que serve: catálogo de regras e testes

Documentação de legado que funciona tem duas partes: um catálogo de regras legível por gente de negócio, e testes que provam que o sistema novo se comporta como o antigo.

O catálogo de regras

Cada regra ganha uma ficha curta, com identificador estável, para que possa ser citada no código novo, nos testes e nas conversas. Um modelo de ficha, preenchido com um exemplo ilustrativo (a mesma regra usada como exemplo no artigo sobre conversores):

O campo Situação é o que dá valor ao catálogo: confirmada, em dúvida, bug conhecido (o sistema faz, mas não deveria — decidir se corrige na migração) ou morta. O campo Fonte garante rastreabilidade: qualquer pessoa consegue voltar ao código antigo e conferir.

Testes de caracterização (golden master)

O catálogo descreve; o teste prova. Um teste de caracterização — termo popularizado por Michael Feathers no livro Working Effectively with Legacy Code — registra o comportamento atual do sistema, certo ou errado, para que qualquer mudança seja percebida. A variante mais prática para migração é o golden master: escolher um conjunto de casos reais (por exemplo, algumas centenas de pedidos históricos, cobrindo os casos de borda do catálogo), guardar as entradas e as saídas que o legado produziu e exigir que o sistema novo produza as mesmas.

// Exemplo ilustrativo: golden master a partir de casos exportados do legado
[Theory]
[MemberData(nameof(CasosDoLegado.Pedidos), MemberType = typeof(CasosDoLegado))]
public void Total_do_pedido_igual_ao_do_sistema_antigo(CasoPedido caso)
{
    var total = new CalculadoraTotalPedido()
        .Calcular(caso.Subtotal, caso.Condicao, caso.Uf);

    Assert.Equal(caso.TotalNoLegado, total);
}

Quando um caso falha, há duas possibilidades: o sistema novo errou, ou o antigo sempre esteve errado e ninguém tinha percebido. As duas são valiosas, e a segunda vira uma decisão de negócio registrada no catálogo — não uma surpresa em produção.

Como a IA ajuda — e onde ela erra

Modelos de linguagem mudaram o custo dessa etapa. Ler milhares de linhas de Object Pascal ou de Visual Basic, descrever em português o que cada rotina faz, mapear quem chama quem e rascunhar as fichas do catálogo é trabalho que a IA acelera muito. Usamos isso em todo projeto.

Mas há erros típicos, e conhecê-los é o que torna o uso seguro:

• Ela só vê o que leu. Uma rotina pode parecer simples porque o trigger que altera o valor depois, ou a configuração global feita na abertura do programa, não estava no trecho analisado.
• Ela descreve a intenção provável, não a escrita. Diante de um acréscimo calculado sobre o bruto, a IA tende a descrever "acréscimo sobre o total" — que é o que pareceria lógico — e a nuance some.
• Ela não sabe o que está morto. Código que nunca é executado é descrito com a mesma convicção do código que roda todo dia.
• Ela não conhece a planilha do lado. O que o sistema não faz e as pessoas fazem à mão não aparece em código nenhum.

Por isso tratamos toda saída de IA como hipótese: ela entra no catálogo com situação "em dúvida" e só passa a "confirmada" depois de conferida no código, no banco e com quem opera.

Como validar com o usuário

Mandar um documento de oitenta páginas para o usuário "dar uma olhada" não valida nada. O que funciona são sessões curtas, por assunto, com exemplos numéricos:

1. Mostrar o caso, não a regra. "Um pedido à vista de R$ 6.000,00 para Curitiba sai por R$ 5.772,00. Está certo?" Qualquer pessoa do financeiro responde isso em segundos; poucas respondem "o acréscimo incide sobre o bruto?".
2. Perguntar pelos desvios. "Isso tem exceção?", "já aconteceu de dar diferente?". As exceções são as regras que faltam no catálogo.
3. Registrar quem validou e quando. Quando surgir dúvida meses depois, a resposta está anotada — e não depende de memória.
4. Separar "o sistema faz" de "o sistema deveria fazer". Divergência entre o código e a prática é comum. A documentação registra as duas coisas, e a decisão do que migrar é do negócio.

A documentação é o ativo que fica com o cliente

Tecnologia envelhece. O C# de hoje vai ser o legado de alguém daqui a quinze anos. O catálogo de regras, os exemplos validados e os testes de caracterização não envelhecem do mesmo jeito: eles descrevem o negócio, não a linguagem. Servem para a migração atual, para a próxima, para treinar gente nova, para responder auditoria e para avaliar qualquer fornecedor — inclusive nós.

Por isso, nos projetos da NasteSoft, a documentação é entregável do cliente, em formato aberto, e não um insumo interno nosso. A NasteSoft e seus parceiros já migraram bancos de dados e aplicações em Delphi, VB6 e .NET, e em todos os casos o que mais valeu a pena preservar não foi o código antigo: foi o conhecimento que estava dentro dele.

Conclusão

Documentar um sistema legado não exige um documento perfeito nem meses parado. Exige método: inventário primeiro, fontes cruzadas (código, banco, telas, relatórios, logs, pessoas e planilhas), regras com exemplo numérico, um catálogo com identificador e situação, testes que travam o comportamento atual e validação feita com casos, não com leitura de texto.

Com isso em mãos, a migração de software legado deixa de ser uma aposta. O sistema novo é escrito sobre regras conhecidas, e cada diferença em relação ao antigo é uma decisão — não um acidente.