O código novo que ninguém consegue manter é pior que o legado.

TL;DR

• Código novo sem documentação, clareza e separação de responsabilidades já nasce com cara de legado ruim.
• Manutenibilidade não acontece por acidente: ela é uma decisão de design tomada enquanto o código ainda está sendo escrito.
• Se uma feature termina e o próximo dev precisa de uma hora para entender o fluxo, o trabalho ainda não está pronto.

Código novo sem documentação é legado desde o dia um

Muita gente trata “legado” como sinônimo de “velho”. Mas isso é só metade da história.

Código legado é difícil porque envelheceu sob pressões que já não existem mais: arquitetura antiga, times trocados, requisitos acumulados, decisões de anos atrás. Há contexto para a bagunça.

Código novo, por outro lado, fica difícil por um motivo bem mais incômodo: ele foi escrito sem pensar em quem vai manter depois.

Quando isso acontece, o código já nasce com defeitos de manutenção:

• funções que fazem cinco coisas diferentes;
• nomes genéricos e inúteis, como `data1`, `process` e `execute`;
• lógica de negócio misturada com detalhe técnico;
• ausência de comentários nos pontos realmente críticos;
• dependências escondidas em vez de explícitas.

Isso não é “falta de tempo” em abstrato. É escolha de design ruim, feita no presente.

O que denuncia negligência no código

Há sinais muito claros de que um código novo foi empurrado para produção sem cuidado suficiente.

O primeiro deles é a função multitarefa. Quando uma única função valida entrada, monta payload, chama API, trata erro e grava log, ela não está “completa”. Ela está inchada.

O segundo é o nome vago. Nome ruim é dívida técnica condensada. `execute()` não explica nada. `sessionId` explica. `data1` só empurra a dúvida para quem vier depois.

O terceiro é a mistura de camadas. Se a regra de negócio está no meio de um detalhe de banco, de fila ou de HTTP, o código ficou dependente demais do ambiente em que nasceu.

O quarto é a ausência de comentário no ponto de decisão. Comentário bom não repete o código. Ele explica o porquê:

• por que esse fluxo existe;
• por que esse atalho foi aceito;
• por que esse caso é tratado de forma diferente;
• por que a solução não foi simplificada mais.

Sem isso, o próximo mantenedor precisa reconstruir a intenção na marra.

Manutenibilidade é propriedade de design

Código mantível não é uma consequência feliz. É um projeto deliberado.

Quem escreve pensando em manutenção faz escolhas que parecem pequenas, mas mudam tudo:

• nomeia com precisão;
• separa responsabilidades;
• reduz acoplamento;
• preserva a leitura linear;
• deixa os pontos de extensão claros;
• documenta as decisões, não o óbvio.

Uma função que valida não deveria salvar. Uma camada de domínio não deveria saber como o HTTP serializa resposta. Uma regra de negócio não deveria depender de detalhes temporários da interface.

Isso não é perfumaria. Isso é o que permite evoluir sem reescrever tudo a cada mudança.

Também existe uma armadilha comum: tentar deixar o código “perfeito” em vez de deixá-lo extensível.

Perfeição paralisa. Extensibilidade protege.

O objetivo não é produzir uma obra-prima de laboratório. É produzir algo que outra pessoa consiga abrir, entender e mexer sem medo.

Debt técnico novo nasce errado quando você ignora o acabamento

Toda equipe conhece o debt antigo. Ele tem história, tem ferida, tem camadas.

Mas o debt novo é especialmente traiçoeiro porque ainda não tem contexto acumulado. Ninguém sabe exatamente por que aquela decisão foi tomada. Ninguém sabe se ela era provisória. Ninguém sabe onde está a próxima quebra.

Quando você entrega uma feature “funcionando”, mas feia, confusa e sem documentação, você não encerrou o trabalho. Você contraiu uma obrigação futura.

E pior: essa obrigação já nasce sem juros baixos.

Por isso, feature pronta de verdade não é só feature que passa no teste. É feature que deixa o caminho razoavelmente limpo para o próximo desenvolvimento.

Uma prática simples ajuda muito: ao terminar uma implementação nova, reserve um tempo para o “deixar mantível”:

• refatorar nomes e responsabilidades;
• remover duplicações;
• escrever comentários onde a intenção não é óbvia;
• adicionar testes nos limites e casos críticos;
• revisar se a estrutura aguenta a próxima mudança esperada.

Esse tempo não é luxo. É parte do custo real de entregar software.

Como transformar código novo em algo sustentável

Se o seu objetivo é construir software que não apodreça rápido, a disciplina precisa aparecer já na escrita.

Algumas regras ajudam bastante:

1. nomeie com precisão, mesmo que demore mais alguns segundos; 2. mantenha uma função com uma responsabilidade principal; 3. extraia o que é regra de negócio do que é infraestrutura; 4. escreva comentários para explicar decisões, não detalhes triviais; 5. refatore antes que a complexidade se espalhe; 6. teste os pontos onde uma mudança futura provavelmente vai tocar.

O benefício aparece na primeira revisão, na segunda alteração e, principalmente, quando alguém novo entra no código.

A pergunta certa não é “isso funciona agora?”. A pergunta certa é “isso vai continuar funcionando quando alguém mexer daqui a seis meses?”.

Fechamento

Culpar o legado é fácil. Difícil é admitir que muita base ruim começa nova, com cara de solução moderna, mas já carrega o desleixo que depois será chamado de tradição. Se o código novo vira legado instantaneamente, o problema não é o tempo: é negligência.

Leitura relacionada

• Código limpo não é estética: é estratégia de sobrevivência — porque a manutenção começa no desenho das responsabilidades, não na pressa de entregar.
• Quando a pressa destrói a revisão e a revisão destrói o time — um lembrete de que o custo de não revisar bem aparece depois, quando ninguém quer tocar no que foi feito.
• Dívida técnica não é um vilão abstrato: ela mora nos detalhes — útil para enxergar como escolhas pequenas se acumulam até virar travamento estrutural.