Clean Code: princípios práticos para times brasileiros em 2026

Clean Code, publicado por Robert C. Martin em 2008, virou referência quase obrigatória em entrevistas técnicas no Brasil. Mas o livro tem quase 20 anos, e a comunidade já reviu várias das suas recomendações. Este artigo resume os princípios que continuam úteis, mostra exemplos em TypeScript e aponta onde aplicar literalmente o livro pode piorar o código.

O que Clean Code propõe

O livro defende que código é lido muito mais do que escrito, então otimizar para leitura paga dividendos ao longo da vida do projeto. Os capítulos cobrem nomes, funções, comentários, formatação, objetos, tratamento de erros e testes. Não é um padrão fechado: é um conjunto de heurísticas com exemplos em Java.

Princípios que envelheceram bem

1. Nomes que revelam intenção

Variáveis e funções devem ser nomeadas pelo que representam, não pelo tipo ou pela posição. O custo de digitar um nome longo é desprezível frente ao custo de reler o código.

// ruim
const d = 7; // dias até expirar
function fn(u: User, l: Item[]) { /* ... */ }

// melhor
const diasAteExpirar = 7;
function calcularTotalDoCarrinho(usuario: User, itens: Item[]) { /* ... */ }

2. Funções pequenas com uma responsabilidade

Funções com 5–15 linhas são mais fáceis de testar, nomear e reusar. O limite exato não importa; o que importa é cada função fazer uma coisa identificável. Quando você precisa escrever “e” na descrição (“valida e salva e envia email”), provavelmente são três funções.

3. Evite efeitos colaterais escondidos

Uma função chamada calcularImposto() não deveria alterar o estado da sessão nem enviar email. Efeitos colaterais devem estar explícitos no nome ou centralizados em camadas dedicadas (serviços, repositórios).

4. Trate erros como cidadãos de primeira classe

Erros não são exceções no sentido coloquial — fazem parte do contrato. Use tipos de retorno explícitos (Result, Either) ou throws documentados, e nunca engula erros com catch vazio. O TypeScript ajuda com unknown em catch desde 4.4.

// trate o erro, não o esconda
try {
  await salvarPedido(pedido);
} catch (err) {
  if (err instanceof PedidoInvalidoError) {
    return { ok: false, motivo: err.message };
  }
  logger.error({ err }, "falha inesperada ao salvar pedido");
  throw err;
}

5. Teste o que importa, não a sintaxe

Cobertura de 100% não é sinônimo de qualidade. Foque testes em comportamentos observáveis (entrada → saída, efeitos visíveis) em vez de detalhes de implementação. Testes acoplados à estrutura interna quebram a cada refatoração legítima.

Princípios que envelheceram mal

1. "Funções devem ter no máximo 4 linhas"

O livro chega a sugerir funções de 2–4 linhas. Na prática, extrair tudo gera um efeito conhecido como over-decomposition: o leitor precisa pular entre 8 arquivos para entender uma rotina linear. Dan Abramov, em "The Wet Codebase" (2019) e "Goodbye, Clean Code" (2020), mostra como a abstração prematura cria acoplamento pior que a duplicação.

2. Comentários são quase sempre ruins

O livro recomenda eliminar comentários sempre que possível, alegando que código bom se explica sozinho. Funciona para lógica trivial. Para regras de negócio complexas, integrações externas com APIs erráticas ou workarounds de bugs conhecidos, comentários explicando o porquê (não o quê) são essenciais. John Ousterhout (A Philosophy of Software Design, 2018) defende explicitamente o oposto: comentários são parte do design.

3. Hierarquias de herança profundas

Os exemplos em Java do livro recorrem a herança que hoje seria considerada antipadrão. Composição sobre herança é a recomendação mainstream desde GoF (1994) e foi reforçada no movimento de Domain-Driven Design e na própria evolução de TypeScript/React (hooks > HOC > mixins).

Métricas objetivas que ajudam mais

Ferramentas como ESLint (plugin sonarjs), SonarQube e CodeClimate calculam essas métricas em CI. Defina limites no pipeline e falhe o build quando ultrapassar — é mais objetivo do que revisão subjetiva em PRs.

Refatoração: quando vale o custo

Refatorar tem custo: tempo, risco de regressão e revisão de PR. A regra do escoteiro ("deixe o código mais limpo do que encontrou") só funciona se as mudanças forem pequenas e cobertas por testes. Refatorações grandes (>500 linhas) precisam de uma justificativa explícita: bug recorrente, performance, ou bloqueio para uma nova feature.

• Sempre refatore: quando você está prestes a alterar a função (custo marginal próximo de zero).
• Avalie caso a caso: código duplicado em 3+ lugares; nomes confusos que já causaram bug em produção.
• Evite: código legado que ninguém mais toca, está em produção há anos e ninguém abriu issue. Custo > benefício.

Checklist prático para code review

1. O nome da função descreve o que ela faz sem precisar abrir o corpo?
2. Há efeitos colaterais não óbvios pelo nome?
3. Funções com mais de 30 linhas têm justificativa (algoritmo, parser, configuração estática)?
4. Erros são tratados com tipo específico ou apenas catch genérico?
5. Há testes para o comportamento novo, não só para a implementação?
6. Comentários explicam o porquê das decisões não óbvias?

Perguntas frequentes

Fontes consultadas

• Robert C. Martin — Clean Code (Prentice Hall, 2008)
• John Ousterhout — A Philosophy of Software Design (2018)
• Dan Abramov — Goodbye, Clean Code
• Dan Abramov — The Wet Codebase (talk)
• SonarSource — Cognitive Complexity (white paper)
• ESLint — sonarjs plugin