Esse código está uma bagunça, precisamos refatorar tudo.” Quase todo time já ouviu, ou disse, essa frase. O problema é que “tudo” não cabe em sprint nenhuma, e a frase não ajuda ninguém a decidir por onde começar.

Dívida técnica é a diferença entre a estrutura que o sistema tem hoje e a estrutura de que ele precisa para continuar evoluindo sem sofrimento. A metáfora financeira ajuda: o principal é o esforço para melhorar; os juros aparecem como tempo extra em cada mudança, defeitos, medo de mexer e dependência de poucas pessoas. A diferença é que, aqui, ninguém manda o extrato. O valor precisa ser estimado com evidência.

Nem toda dívida é igual

Martin Fowler propôs um quadrante que cruza intenção (deliberada ou inadvertida) e prudência (prudente ou imprudente). Adaptando:

A primeira linha é engenharia legítima. A segunda é a que costuma doer mais tarde.

Sinais de que os juros estão altos

• Uma mudança pequena exige ajustes espalhados por vários lugares.
• O mesmo módulo muda por motivos completamente diferentes.
• Módulos que não conseguem evoluir separados, por dependência cíclica.
• Comportamentos parecidos, duplicados, que divergiram com o tempo.
• Testes que quebram quando a implementação muda, mesmo sem mudar o comportamento.

Um sinal sozinho não obriga a refatorar. Duplicação estável, num código que ninguém toca, pode custar quase nada. Já uma dependência ruim numa área que muda toda semana cobra juros toda semana.

Onde pagar primeiro

Cobertura, complexidade e duplicação ajudam a localizar áreas suspeitas, mas não devem virar meta isolada. A pergunta que mais ajuda a priorizar é outra: onde a complexidade e a frequência de mudança se encontram?

Arquivos que mudam muito e concentram complexidade, os chamados hotspots, costumam dar o melhor retorno. Se além disso uma falha ali tem alto impacto, a prioridade sobe mais. O histórico do controle de versão já entrega boa parte dessa informação: quais arquivos mais aparecem nos commits e nos defeitos dos últimos meses.

Refatorar em passos pequenos

Refatorar é mudar a estrutura sem mudar o comportamento. Se a regra muda junto, são duas mudanças, e vale separá-las para facilitar revisão e reversão. Um roteiro que funciona:

1. Defina o comportamento que precisa ser preservado.
2. Crie testes de caracterização, que registram o que o código faz hoje, inclusive as esquisitices.
3. Faça uma transformação pequena.
4. Rode testes e análise estática.
5. Integre antes que a mudança cresça demais.

E reescrever do zero?

Reescrever parece quitar a dívida de uma vez. Na prática, joga fora conhecimento acumulado, reinicia a descoberta dos casos extremos e obriga a manter dois sistemas durante a transição. Projetos de reescrita costumam subestimar o comportamento implícito do legado.

Num caso que conto no livro, um sistema interno precisava ser aberto para acesso pela internet. Em vez de reescrever o domínio, a equipe colocou uma API em FastAPI como fachada: extraiu o acesso ao legado dos endpoints, centralizou validações, criou testes de caracterização para os fluxos expostos e foi migrando caso de uso por caso de uso. O legado ficou protegido por contratos e cercado por limites que permitem substituí-lo aos poucos.

Código limpo, nesse contexto, é o que torna a próxima mudança menor e mais segura.

Para ir além

O capítulo 11 do livro Engenharia de Software: Fundamentos e Práticas aprofunda código limpo, os tipos de dívida, testes de caracterização, o padrão Strangler Fig para substituição gradual e quando não refatorar.

Conheça o livro. E se a dívida que mais pesa no seu time é de arquitetura, o artigo sobre monólito modular e microsserviços ajuda.