Código legado é arqueologia: como escavar sem destruir

TL;DR

• Código legado não é problema de arquitetura — é problema de contexto perdido.
• Teste é a única documentação que não mente: o que passa, o código faz.
• Refatoração só é segura quando é incremental: pequena, testada, deployada, repetida.
• A regra dos 30 minutos: se passou meia hora sem escrever um teste, peça ajuda.
• Migração é processo (Strangler Fig), não projeto: novo nasce em paralelo, legado morre aos poucos.

Por que código legado resiste a quem sabe programar

O código legado não é um problema de habilidade técnica. É artefato de um contexto que mudou, mas o código ainda vive. As pessoas que escreveram o código em 2015 estão em outras equipes, ou já não trabalham mais na empresa. O comportamento atual está nas linhas, não nos comentários ou no fluxo de trabalho descrito em uma wiki que ninguém atualiza.

Herança não é legado — é um desafio de contexto. A única fonte de verdade sobre o que o sistema faz é o teste. O código é o mapa, e o teste é a bússola.

public class EstoqueService
{
    public int Buscar(int sku)
    {
        // Código legado que ninguém ousa mexer
        var produto = _repositorio.Buscar(sku);
        return produto?.Quantidade ?? 0;
    }
}

Você não pode depender de uma documentação que foi escrita antes do código existir. Nem dos comentários que foram feitos com base em uma versão antiga. Nem das pessoas que já não estão mais aqui para explicar.

Teste é a única documentação que não mente

O teste é o único lugar onde o comportamento atual está escrito. E ele é verdadeiro — ou você tem um teste que falha, ou ele passa. Se estiver passando, significa que o código faz aquilo que o teste diz que faz.

Antes de qualquer alteração, adicione um teste que cubra o comportamento atual. Isso é uma forma de escavar com mapa: você não está apenas olhando para o chão — você está validando o que está lá.

Três sinais de que o teste capturou o comportamento certo:

• O teste passa em ambientes de desenvolvimento e produção.
• O teste é específico, com valores de entrada claros e saídas esperadas.
• O teste não depende de implementação, mas sim do comportamento observável.

[Fact]
public void Deve_Retornar_Quantidade_Zero_Se_Produto_Nao_Existe()
{
    var service = new EstoqueService(_repositorio);
    var resultado = service.Buscar(999);

    Assert.Equal(0, resultado);
}

Se você tentar entender o código e não conseguir escrever um teste que represente o comportamento atual, pare. Se passou 30 minutos sem entender, é hora de pedir ajuda. Não tente reinventar o que já existe — você vai apenas criar mais ruínas.

Refatoração incremental: o único seguro viável

Refatorar tudo de uma vez é um erro de escavação. Você pode acabar destruindo a estrutura sem perceber. O caminho certo é identificar uma parte pequena do código, adicionar um teste que prove seu comportamento atual, refatorar aquela parte, validar o teste e então continuar.

Ciclo de refatoração:

• Identifique uma parte do código com impacto limitado.
• Escreva um teste caracterizador para ela.
• Refatore com pequenas mudanças.
• Valide o teste após a mudança.
• Deploy se tudo estiver ok.
• Repita com outra parte.

Se você tem um método com 100 linhas, não tente reescrever tudo. Comece com uma parte menor. Isso mantém o risco baixo, permite que você entenda melhor o comportamento e evita quebrar algo sem perceber.

A regra dos 30 minutos: quando parar de escavar

Se você passou 30 minutos tentando entender uma parte do código legado e não conseguiu escrever um teste que represente o comportamento atual, pare. Pergunte ao colega mais experiente. Isso é um sinal de que você está perdido no mapa.

Três sinais de que você está perdido:

• Não consegue escrever um teste simples.
• Estuda o código por mais de 30 minutos sem avançar.
• Se sente frustrado e com pressa para resolver tudo sozinho.

Não tente resolver tudo sozinho. A escavação é mais segura com uma equipe. A frustração de entender o código e não conseguir provar seu comportamento é real — mas não é motivo para continuar sozinho por mais tempo.

Strangler fig: migração como processo, não como projeto

Reescrever um sistema do zero é um caminho para o fracasso. O jeito certo é escrever o novo código em paralelo, desviar tráfego gradualmente e deixar o legado morrer com o tempo.

Martin Fowler chamou isso de Strangler Fig Pattern. Você não substitui tudo de uma vez — você constrói algo novo, conecta, e vai desligando partes antigas conforme a nova solução cresce.

Benefícios do Strangler Fig:

• Risco reduzido na migração.
• Entrega contínua de novas funcionalidades.
• Controle sobre o tempo de vida do legado.

O que muda quando você herda o código

Você não herda apenas linhas. Herda o peso do tempo, das decisões que foram tomadas sem você estar presente. Você começa a responder pelo código, e isso muda sua relação com ele.

Legado é uma herança que precisa ser escavada com cuidado. O tempo passa, o código sobrevive, e você é quem precisa entender o que estava ali antes.

• Não chute a intenção do código antigo — leia o commit, pergunte, ou prove com teste.
• Não culpe quem saiu — a decisão de 2015 fazia sentido no contexto de 2015.
• Não prometa reescrita do zero — Strangler é caminho, destino é uma sprint épica que ninguém termina.

Trabalhar em código legado é, antes de tudo, uma questão de respeito pelo tempo dos outros e pelo seu próprio. Cada refatoração pequena é uma camada escavada, entendida e reescrita com o que se aprendeu. O legado não é inimigo a ser derrotado em uma sprint épica; é herança a ser preservada com a precisão de um arqueólogo. Antes de mudar o que está ali, escreva o teste que prova o que está ali. Depois, mexa pequeno.

Leitura relacionada

• O código novo que ninguém consegue manter é pior que o legado — o lado oposto: como o código que está nascendo hoje pode já chegar velho, e por que manutenibilidade é decisão de design, não acidente.
• Programação em par com IA: aceleração evolutiva — usar IA como par reduz a chance de estragar código que não se entende, porque cada decisão vira diálogo, não monólogo.
• IA programava em 2020. A percepção demorou três anos — o que muda quando o tempo entre “código escrito” e “código mantido” encolhe, e por que legado também é isso.