Lendo código legado como um arqueólogo

Já li mais código escrito por estranhos do que código que escrevi. Depois de algumas centenas de sistemas, parei de ler código legado como engenheiro procurando o que está errado e passei a ler como arqueólogo procurando o que aconteceu. A segunda abordagem encontra mais bugs, e encontra mais rápido.

Um arqueólogo não julga uma ruína por não ser um prédio moderno. Ele pergunta para que servia, quem construiu, o que mudou e por que as camadas estão na ordem em que estão. Código legado merece o mesmo respeito, não porque é bom, mas porque a história que ele conta é o caminho mais rápido para entender o que vai quebrar quando você mexer.

Estratigrafia: as camadas contam a história

Toda base de código com mais de três anos tem estratos visíveis. O estilo original, geralmente consistente e ingênuo, de quando uma ou duas pessoas escreviam tudo. Uma segunda camada com nomes diferentes e uma abstração nova, de quando o time cresceu ou um novo líder chegou. Uma terceira camada de remendos que ignora os dois estilos anteriores, do período em que ninguém tinha tempo. E às vezes uma quarta, uma migração pela metade para algo moderno, abandonada no meio.

Mapeio isso antes de ler qualquer função a fundo. Git blame por diretório, ordenado por data, faz a maior parte do trabalho. Os pontos de transição entre camadas são onde as surpresas moram. É ali que duas convenções se encontram, que o tratamento de erro antigo entrega para o novo, que uma forma de dado foi traduzida e algo se perdeu.

Artefatos: as coisas estranhas são as coisas importantes

O instinto mais útil do arqueólogo é que qualquer coisa esquisita provavelmente foi colocada ali de propósito. Um sleep fixo de 350 milissegundos. Um loop de retry que tenta exatamente quatro vezes. Uma verificação de id de cliente que não aparece em nenhum outro lugar. Um bloco comentado com data de seis anos atrás.

Engenheiros juniores apagam isso como limpeza. Eu trato cada um como evidência de um incidente que ninguém documentou. O sleep existe porque algum sistema a jusante precisava de um momento, e talvez ainda precise. Os quatro retries foram calibrados contra alguma coisa. O id de cliente especial foi um hotfix de produção para alguém importante. Antes de remover qualquer um, tento encontrar o incidente. Mensagem de commit, referência de ticket, comentário num arquivo vizinho. Se não encontro, não removo; envolvo num comentário dizendo que é inexplicado e adiciono monitoramento em volta.

Procedência: quem escreveu e sob qual pressão

Código escrito na semana antes de um lançamento é diferente de código escrito num mês tranquilo, e a diferença importa quando você estima quão seguro é mudar. Olho a densidade de commits em cada módulo. Uma rajada de trinta commits em três dias seguida de silêncio por dois anos é uma funcionalidade que foi feita às pressas e nunca mais tocada. Funciona, no sentido de que ninguém reclamou, mas provavelmente nunca foi exercitada fora do caminho feliz.

O padrão inverso, commits pequenos e constantes ao longo de anos, é um módulo que foi mantido, entendido e provavelmente testado pelas pessoas que o mantiveram vivo. Esses são mais seguros de mudar, mesmo que o código seja mais feio, porque a feiura já foi revisada muitas vezes.

Reconstrução: recupere a intenção antes de reconstruir o código

O último passo, antes de propor qualquer mudança, é escrever o que o código está tentando fazer em frases simples, como se explicasse para quem o escreveu. Não o que ele faz linha a linha; para que serve. 'Este job reconcilia os pagamentos de ontem contra o relatório do provedor e sinaliza divergências acima de um limite.' Se não consigo escrever essa frase, não entendo o módulo o suficiente para mudá-lo.

Depois listo as perguntas que o código levanta e que não consegui responder só pelo código. Por que o limite é porcentagem aqui e valor fixo ali? Por que este caminho pula o log de auditoria? Essas perguntas vão para quem está lá há mais tempo, e as respostas geralmente remodelam o plano.

Código legado é a documentação mais honesta que uma empresa tem. Ele registra toda decisão que realmente foi para produção, incluindo as que ninguém admitiria numa revisão de design. Leia como registro, não como bagunça, e ele vai te dizer exatamente onde vai falhar da próxima vez.