Higiene de Mudanças e Artesanato de Código
Visão Geral
Como as mudanças são moldadas e como o código é escrito. Dois temas: separe mudança estrutural de mudança comportamental e diga o que você quer com o mínimo de engenhosidade que funcione.
Higiene de Mudanças
- Mudanças estruturais antes das comportamentais, validadas de forma independente. Reorganizar (dividir arquivos, renomear, adicionar comentários) é uma etapa separada e verificável de alterar comportamento (novas restrições, lógica alterada). Nunca misture as duas em uma mudança indivisível — um revisor não consegue distinguir uma reorganização segura de mudanças reais de lógica.
- Uma preocupação por mudança. Uma mudança tem um propósito único e declarável.
- Melhore o código em que você está trabalhando quando seus problemas afetarem sua tarefa (deixe o acampamento mais limpo) — mas não inicie refatorações não relacionadas. Mantenha o foco no objetivo.
Artesanato de Código
- Explícito sobre implícito. Sem curingas onde nomes pertencem, sem casts implícitos, sem string vazia ou sentinelas mágicas. Diga o que você quer.
- Nomes descritivos. Funções/variáveis descrevem o que fazem; siga os idiomas do ecossistema e da linguagem.
- Comente a intenção, não a mecânica. Explique o porquê quando não for óbvio; pule comentários em código autoexplicativo.
- Unidades pequenas e de propósito único. Para qualquer unidade, você deve ser capaz de afirmar o que ela faz, como usá-la e de que depende — sem ler suas entranhas. Um arquivo grande geralmente está fazendo demais.
- DRY em código de produção, com bom senso. Duplicação é um sinal, não um erro automático. A segunda ocorrência quase idêntica aciona uma decisão deliberada: abstrair ou registrar por que não. Abstraia significado compartilhado, nunca formato coincidente — coisas que parecem iguais, mas mudam por razões diferentes, devem permanecer separadas.
- Siga os padrões do ecossistema. Use os idiomas e bibliotecas bem suportados que um profissional competente espera. Não reinvente o que a plataforma já resolveu.
As Tensões Nomeadas
- DRY vs. abstração prematura: código de produção abstrai com base em repetição demonstrada de intenção, não em repetição antecipada de formato. Quando estiver em dúvida, espere pela terceira ocorrência (YAGNI governa o desempate).
- DRY vs. DAMP: código de produção é DRY; código de teste é DAMP (clareza sobre desduplicação, veja
tests-as-a-control). Aplicar DRY em testes é uma violação.
Racionalizações Comuns
| Desculpa | Realidade |
|---|---|
| "Vou renomear e adicionar a funcionalidade em um commit" | Estrutura e comportamento em um único diff são irrevisáveis. Separe-os. |
| "Duas cópias, preciso aplicar DRY agora" | Segunda ocorrência = decida. Mesma forma ≠ mesmo significado. Duplicação coincidente deve permanecer separada. |
| "Já que estou aqui, vou refatorar aquele outro módulo" | Refatoração não relacionada expande escopo e risco. Anote; não faça agora. |
| "Um one-liner inteligente é mais elegante" | Explícito supera inteligente. Otimize para o próximo leitor. |
Bandeiras Vermelhas — PARE
- Um diff que move código e altera seu comportamento ao mesmo tempo
- Um PR cujo propósito precisa da palavra "e" para ser descrito
- Abstrair na primeira aparição de similaridade, ou com base em repetição antecipada (não real)
- Um arquivo que você não consegue mais manter na sua cabeça
Racionalização completa: Artigos V e VI da constituição, agrupados em engineering-constitution/references/engineering-constitution.md.