A próxima pessoa a manter seu código pode ser você, numa terça-feira corrida, quatro meses depois e sem memória alguma daquela decisão “óbvia”. Escrever pensando nela não é comentar cada linha. É reduzir o trabalho de arqueologia.
O código precisa mostrar intenção, limites e maneiras de verificar o comportamento. A documentação entra onde o motivo não cabe naturalmente na implementação.
Nomes poupam tradução
processData não conta quase nada. confirmarPagamento informa propósito e sugere as regras que deveríamos procurar. Bons nomes não deixam o código autoexplicativo em sentido mágico; apenas evitam esconder informação útil.
Consistência vence criatividade. Se UI, API e domínio falam do mesmo conceito, uso o mesmo termo. Se os conceitos diferem, mostro a tradução na fronteira.
A estrutura oferece pontos de entrada
Organizar por capacidade ajuda quem chega com uma pergunta de produto. Dentro do módulo, separo domínio, aplicação e infraestrutura quando isso esclarece responsabilidades — não para manter pastas vazias.
- README local: apresenta propósito, contratos e execução.
- Teste: mostra exemplos e limites do comportamento.
- Tipo: registra dados necessários e estados permitidos.
- Decisão: preserva o motivo que o código não revela.
Comentário bom explica estranheza
“Incrementa contador” envelhece mal e repete a sintaxe. Comentários úteis explicam restrição externa, compromisso ou razão para uma solução aparentemente esquisita. Antes deles, tento melhorar nome e estrutura.
Uma decisão arquitetural difícil merece um registro curto: contexto, opção escolhida e consequências. É suficiente para não repetir a investigação do zero.
Colaboração deixa marcas
Com Sinaxys e Entrega Contínua, contratos claros facilitaram trabalho em integrações com Stripe, N8N e WhatsApp. Pull requests menores, riscos descritos e passos de teste tornam a revisão uma conversa real.
Na ANIMAPS, onde também respondo pela evolução do produto, atalhos sem contexto voltam rapidamente como perguntas. Essa proximidade é uma professora bastante direta.
Respeitar quem vem depois é permitir que essa pessoa entenda, questione e troque uma decisão antiga.
Executar e diagnosticar também contam
Comandos previsíveis, ambiente validado e mensagens acionáveis reduzem diferenças entre máquinas. Exemplos de configuração nunca devem carregar segredos, mas precisam explicar o que é obrigatório.
Em produção, logs com correlação ajudam a seguir o fluxo. Quem investiga um incidente também é o “próximo desenvolvedor” para quem estamos escrevendo.
Conclusão
Código pensado para a próxima pessoa não precisa ser perfeito. Precisa oferecer bons pontos de entrada, exemplos confiáveis e decisões explicáveis. Assim, o esforço de leitura vai para o problema novo, não para reconstruir uma intenção que o projeto poderia ter preservado.