Código legado:
mudar o que
ninguém quer tocar

1.1 A definição que serve

Uma definição complementar, mais crua: código legado é código que você tem medo de mudar. Repare que ambas admitem a mesma coisa incómoda — que se pode escrever código legado esta tarde, e a maior parte das equipas escreve.

1.2 O que se sente e o que é

1.3 A escala do assunto

A imagem do trabalho de programação — campo aberto, projeto novo, decisões de raiz — descreve uma fração pequena do que se faz. O resto é acrescentar comportamento a sistemas que já existem, que já têm clientes, e que não podem parar. É esse o trabalho, e é sobre ele que menos material existe.

1.4 O que esta apostila é

1.5 A regra que organiza tudo o resto

2.1 Ler código que não se percebe

• Comece pelas fronteiras, não pelo meio. Onde entram os pedidos, o que sai para a base de dados, que ficheiros se leem. As fronteiras são poucas e definem o sistema melhor do que o núcleo.
• Siga um caso real do princípio ao fim. Um único pedido, desde o clique até à linha gravada. Aprende-se mais nisto do que a ler cinquenta ficheiros por ordem alfabética.
• Desenhe enquanto lê. Um diagrama feito à mão, mesmo errado, obriga a decidir o que é importante — e as correções ao desenho são a aprendizagem.
• Anote as perguntas, não as respostas. A lista de "porque é que isto está aqui?" é o inventário do que ainda não se sabe, e vai ser útil no capítulo 3.

2.2 O que o histórico do repositório diz

O git é o instrumento de arqueologia mais subaproveitado que existe (Git & GitHub):

2.3 Fazer o sistema falar

• Registo temporário e generoso. Acrescente registos em pontos-chave, corra um caso real, leia a sequência, e retire-os. Vale mais que qualquer diagrama desatualizado.
• Meça antes de otimizar. A intuição sobre onde está a lentidão erra quase sempre. Um profiler uma vez poupa uma semana de refatoração do sítio errado.
• Instrumente antes de mudar. Se não consegue ver o comportamento atual em produção, não vai conseguir provar que a mudança não o alterou.
• Conte o que existe. Quantas rotas, quantas tabelas, quantos jobs agendados. O número costuma ser diferente do que toda a gente diz.

2.4 As perguntas às pessoas

Parte do sistema não está no código: está nas cabeças, e sai com as perguntas certas. "Porque é que isto está assim?" põe as pessoas na defensiva; "o que é que isto estava a resolver na altura?" devolve a história. Quase toda a estranheza teve uma boa razão — um cliente grande, um prazo, uma limitação que já não existe. Saber qual é o que permite decidir se a razão ainda se aplica.

3.1 O teste que não sabe o que devia acontecer

Um teste normal afirma o comportamento correto. Num sistema legado ninguém sabe qual é — e às vezes o comportamento errado já é aquilo de que os clientes dependem. O teste de caracterização resolve isto invertendo o objetivo:

3.2 Testes de aprovação, para quando a saída é grande

Quando o resultado é um relatório, um HTML, um ficheiro ou uma estrutura enorme, escrever afirmações campo a campo é impraticável. A variante: guarde a saída inteira num ficheiro de referência aprovado e, a cada execução, compare tudo. Qualquer diferença aparece como diff.

• É desproporcionalmente eficaz em código legado: cobre milhares de campos com uma linha de teste.
• Exige eliminar o que varia sozinho — datas, identificadores aleatórios, ordem de coleções. Normalize antes de comparar, senão o teste falha todos os dias por nada.
• Perigo: aprovar um diff sem o ler. Um teste de aprovação vale exatamente o cuidado com que se aprovam as diferenças.

3.3 Por onde começar a cobertura

3.4 Quando nem isso dá

Há código que não se consegue chamar de teste nenhum sem o mudar antes — e mudá-lo sem rede é o que se queria evitar. Três saídas legítimas:

• Refatorações comprovadamente seguras da ferramenta. Renomear ou extrair método com o refactor automático do IDE, sem escrever nada à mão, é seguro o bastante para abrir caminho.
• Comparação em paralelo. Corra o código antigo e o novo lado a lado com tráfego real, sem usar o resultado do novo, e compare. Caro, e às vezes é a única prova possível.
• Aceitar o risco, em pequeno. Uma alteração minúscula, revista por outra pessoa, com plano de reversão. Melhor do que ficar paralisado — desde que seja decisão consciente e não hábito.

4.1 O que é uma costura

function calcularFatura(id) {
  const bd = new LigacaoBD(CONFIG.url);
  const email = new ServidorEmail();
  const hoje = new Date();
  // ... 200 linhas
}

function calcularFatura(id, deps) {
  const { bd, email, agora } = deps;
  // ... as mesmas 200 linhas
}

A transformação acima chama-se parametrizar dependências e é a mais rentável do ofício: não muda comportamento nenhum, o compilador ou os testes existentes apanham os erros, e desbloqueia tudo o resto.

4.2 O catálogo de quebra de dependências

4.3 O relógio, o acaso e a rede

Três dependências invisíveis que estragam mais testes do que todas as outras juntas, porque não parecem dependências:

• A hora atual. Um teste que passa às 10h e falha às 23h59 do dia 31 tem aqui a causa.
• Números aleatórios e identificadores. Injete o gerador; nos testes, um determinista.
• Chamadas de rede. Além de lentas, tornam os testes dependentes de coisas fora do seu controlo. Substitua na fronteira, não em cada sítio onde são usadas.

4.4 Não deixe a costura virar arquitetura

5.1 As transformações que resolvem quase tudo

Não é preciso saber cinquenta nomes. Renomear e extrair função resolvem a maioria dos casos reais, e são as duas que a ferramenta faz sozinha sem risco.

5.2 O tamanho do passo

5.3 A regra do escuteiro, e o seu limite

"Deixe o acampamento mais limpo do que o encontrou" — melhore ligeiramente o código por onde passar. É bom conselho e tem duas armadilhas:

• A limpeza vai no mesmo commit que a funcionalidade e o diff fica ilegível. Separe: um commit só de refatoração, outro só de comportamento (a regra de 1.5).
• A limpeza cresce. Começa em renomear uma variável e acaba a reorganizar um módulo. Ponha um limite de tempo antes de começar; o que ficar por fazer vai para a lista, não para o pull request.

5.4 Quando a refatoração dá para trás

6.1 Figueira estranguladora

A metáfora é botânica: a figueira cresce à volta da árvore hospedeira, ramo a ramo, até a substituir por completo — e nunca há um momento em que não haja árvore.

6.2 Ramificar por abstração

Quando a coisa a substituir está no meio do código e não atrás de uma fronteira de rede, não há onde pôr uma fachada. A alternativa faz-se toda no ramo principal:

1. Crie uma abstração sobre o que existe — uma interface com as operações usadas.
2. Passe todos os chamadores a usá-la, ainda com a implementação antiga por trás. Nada mudou de comportamento.
3. Escreva a implementação nova por trás da mesma abstração.
4. Comute com uma bandeira de funcionalidade: primeiro internamente, depois 1% do tráfego, depois tudo (Feature Flags).
5. Apague a implementação antiga e a abstração, se já não servir para nada.

Vantagem decisiva sobre o ramo longo: todo o trabalho está no ramo principal desde o primeiro dia. Não há merge, não há conflitos, e qualquer pessoa pode continuar o trabalho.

6.3 A comparação em paralelo

Para lógica crítica onde um erro é caro — cálculo de preços, de impostos, de risco —, há um passo intermédio que compensa: correr as duas implementações com tráfego real, devolver o resultado da antiga, e registar as diferenças.

• Dá uma prova empírica em dados reais, com todos os casos-limite que ninguém imaginou.
• Cada diferença é uma pergunta: qual das duas está certa? Frequentemente descobre-se que a antiga tinha um bug que ninguém notara.
• Custa recursos e complexidade, e por isso é temporário. Defina de antemão quando desliga: "duas semanas sem diferenças por explicar".

6.4 O que decide entre eles

7.1 Expandir, migrar, contrair

A regra que atravessa tudo: nunca faça uma alteração de esquema que exija que o código antigo e o novo parem ao mesmo tempo. Durante um deploy, as duas versões coexistem — e durante uma reversão também.

7.2 Migrações que não bloqueiam

• Nunca corra uma migração longa dentro de uma transação de deploy. Separe: a alteração de esquema é uma entrega, o preenchimento de dados é um trabalho em segundo plano.
• Lotes pequenos, com pausa. Mil registos de cada vez, com intervalo. Uma atualização de dez milhões de linhas de uma vez bloqueia a tabela e derruba a aplicação.
• Retomável e idempotente. O processo vai ser interrompido. Tem de poder voltar a correr sem duplicar nada.
• Índices criados sem bloqueio, onde o motor o permita. Um índice criado à moda antiga numa tabela grande é uma paragem não anunciada.
• Ensaie com um volume realista. Uma migração que corre em 2 segundos com mil linhas pode demorar seis horas com dez milhões, e isso não se descobre em produção.

7.3 Os dados que já lá estão são piores do que o esquema diz

7.4 Uma cópia de segurança que ninguém testou não existe

Antes de qualquer alteração irreversível: confirme que existe cópia, que é recente, e — o passo que quase ninguém dá — que já foi restaurada com sucesso pelo menos uma vez. Uma cópia por testar é uma esperança com nome técnico. E escreva o plano de reversão antes, não durante o incidente.

8.1 As quatro opções

8.2 A reescrita total: porque falha

8.3 A conta que decide

8.4 Um caso de congelamento bem decidido

10.1 O que a metáfora da dívida diz e o que esconde

Ward Cunningham cunhou a metáfora com um sentido preciso: entregar depressa com uma estrutura imperfeita é contrair um empréstimo — legítimo, útil, e com juros a pagar em cada alteração futura. A metáfora funciona porque explica a decisão a quem pensa em termos financeiros.

10.2 Traduzir para a linguagem de quem decide

A diferença não é retórica: é que a coluna da direita tem números que podem ser confrontados e permite a quem decide compará-la com outras coisas. A coluna da esquerda pede confiança; a da direita apresenta um caso.

10.3 Onde arranjar os números

• Tempo por alteração, por área. Mesmo grosseiro, do sistema de tarefas.
• Incidentes por módulo. Já está registado; quase nunca é agregado assim.
• Alterações por ficheiro (cap. 2) — mostra onde o custo se repete.
• Alterações falhadas. Quantas correções precisaram de correção. É o indicador mais eloquente que existe e quase ninguém o conta.
• Fator autocarro. Quantas pessoas conseguem mexer em cada área crítica. Quando é 1, é risco de negócio e fala-se dele como tal.

10.4 Não peça um projeto: peça uma percentagem

10.5 Quando a resposta é não

Às vezes a decisão de não investir é correta e não foi tomada por ignorância: uma ronda de financiamento em curso, um cliente decisivo, um sistema a caminho de ser descontinuado. Registe o que disse e siga, sem transformar o assunto numa causa pessoal.

O que se faz nesses períodos: as intervenções de custo quase nulo — cobrir com testes o que se vai mexer, escrever o que se descobre, não piorar. E manter o registo, porque a decisão vai ser revista quando o contexto mudar, e nessa altura os números estarão prontos.

11.1 O que muda mesmo

11.2 O perigo específico

Há um segundo risco, mais silencioso: refatorações grandes ficaram baratas de produzir e continuam caras de rever. Um pull request de 3.000 linhas gerado em cinco minutos consome duas horas de revisão atenta — que ninguém tem — e é aprovado por cansaço. O gargalo mudou de sítio, e é preciso desenhar o processo para o novo sítio.

11.3 Como usar sem se magoar

• Primeiro a rede, depois a IA. Testes de caracterização antes de aceitar qualquer alteração sugerida. Sem eles, não há como distinguir uma boa sugestão de uma catástrofe elegante.
• Peça explicações, não reescritas. "O que faz esta função e que casos-limite trata?" é uma boa pergunta, e a resposta verifica-se. "Reescreve isto melhor" é um convite ao problema de 11.2.
• Peça-lhe para gerar entradas de teste estranhas. É onde brilha: casos-limite que a pessoa não pensaria. E o resultado é validado ao correr.
• Limite o tamanho do que aceita de uma vez — a mesma disciplina de passos pequenos do cap. 5, agora aplicada à revisão em vez da escrita.
• Desconfie da simplificação. Quando o assistente propõe eliminar uma condição por parecer redundante, essa é a hora de ir ao histórico perceber quando é que ela apareceu (cap. 2).

11.4 A assimetria que fica

12.1 As sete regras que sobram de tudo

12.2 Escrever o que se descobriu

Muito do custo do código legado é conhecimento perdido: alguém já percebeu aquele módulo três vezes, e três vezes esse entendimento saiu pela porta. Duas práticas baratas resolvem a maior parte:

• Registos de decisão. Uma página por decisão relevante: contexto, opções, escolha, consequências. Escrita quando se decide, não depois. O valor não está na decisão — está no contexto, que é a parte que se perde e a que faz a decisão parecer absurda cinco anos depois.
• Um comentário quando o código não pode ser óbvio. Não a explicar o que faz — isso reescreve-se —, mas porquê: "o cliente X envia a data neste formato desde 2019; ver ficha 4471". É o comentário que impede a próxima pessoa de "limpar" a estranheza.

12.3 Deixar de produzir legado novo

A pergunta que fecha o assunto: porque é que este sistema ficou assim? Se a resposta for "não havia tempo para testes" e nada mudou, o sistema novo vai ficar igual. As causas são quase sempre organizacionais e conhecidas:

• Prazos negociados sem quem faz o trabalho.
• Nenhuma área com dono — o que não é de ninguém degrada-se.
• Revisão de código como formalidade, não como leitura.
• Rotatividade sem transferência de conhecimento.
• Nenhum espaço regular para trabalho de estrutura (a percentagem do cap. 10).

Melhorar o código sem tocar nestas causas é limpar uma casa com a torneira aberta. É trabalho útil e não resolve.

12.4 Para onde ir a seguir

• Testing & Automação — a rede do capítulo 3, com profundidade e com as ferramentas.
• Arquitetura & System Design — para decidir o destino das migrações do capítulo 6.
• Git & GitHub — a arqueologia do capítulo 2 e a disciplina de commits pequenos.
• DevOps, Docker & Kubernetes — entregas pequenas e reversíveis são o que torna tudo isto possível.
• Aceleração de Código com IA e O Futuro da Engenharia de Software — o capítulo 11, dos dois lados.