Habilidade de Código Limpo

Esta habilidade incorpora os princípios de "Código Limpo" de Robert C. Martin (Uncle Bob). Use-a para transformar "código que funciona" em "código que é limpo".

🧠 Filosofia Central

"Código é limpo se puder ser lido e aprimorado por um desenvolvedor diferente de seu autor original." — Grady Booch

Quando Usar

Use esta habilidade quando:

• Escrever código novo: Para garantir alta qualidade desde o início.
• Revisar Pull Requests: Para fornecer feedback construtivo baseado em princípios.
• Refatorar código legado: Para identificar e remover "code smells" (cheiros de código).
• Melhorar padrões da equipe: Para alinhar com as melhores práticas do setor.

1. Nomes Significativos

• Use Nomes que Revelam a Intenção: elapsedTimeInDays em vez de d.
• Evite Desinformação: Não use accountList se for realmente um Map.
• Faça Distinções Significativas: Evite ProductData vs ProductInfo.
• Use Nomes Pronunciáveis/Pesquisáveis: Evite genymdhms.
• Nomes de Classes: Use substantivos (Customer, WikiPage). Evite Manager, Data.
• Nomes de Métodos: Use verbos (postPayment, deletePage).

2. Funções

• Pequenas!: Funções devem ser menores do que você pensa.
• Faça Uma Coisa Só: Uma função deve fazer apenas uma coisa e fazê-la bem.
• Um Nível de Abstração: Não misture lógica de negócios de alto nível com detalhes de baixo nível (como regex).
• Nomes Descritivos: isPasswordValid é melhor que check.
• Argumentos: 0 é o ideal, 1-2 é aceitável, 3+ requer uma justificativa muito forte.
• Sem Efeitos Colaterais: Funções não devem alterar secretamente o estado global.

3. Comentários

• Não Comente Código Ruim — Reescreva-o: A maioria dos comentários é um sinal de falha em nos expressarmos em código.
• Explique-se em Código:

  # Check if employee is eligible for full benefits
  if employee.flags & HOURLY and employee.age > 65:
  

  vs

  if employee.isEligibleForFullBenefits():
  

• Bons Comentários: Legais, Informativos (intenção de regex), Esclarecimento (bibliotecas externas), TODOs.
• Comentários Ruins: Murmúrios, Redundantes, Enganosos, Obrigatórios, Ruído, Marcadores de Posição.

4. Formatação

• A Metáfora do Jornal: Conceitos de alto nível no topo, detalhes na parte inferior.
• Densidade Vertical: Linhas relacionadas devem estar próximas umas das outras.
• Distância: Variáveis devem ser declaradas perto de seu uso.
• Indentaçao: Essencial para legibilidade estrutural.

5. Objetos e Estruturas de Dados

• Abstração de Dados: Oculte a implementação por trás de interfaces.
• A Lei de Deméter: Um módulo não deve conhecer os detalhes internos dos objetos que manipula. Evite a.getB().getC().doSomething().
• Data Transfer Objects (DTO): Classes com variáveis públicas e sem funções.

6. Tratamento de Erros

• Use Exceções em Vez de Códigos de Retorno: Mantém a lógica limpa.
• Escreva Try-Catch-Finally Primeiro: Define o escopo da operação.
• Não Retorne Null: Força o chamador a verificar null toda vez.
• Não Passe Null: Leva a NullPointerException.

7. Testes de Unidade

• As Três Leis do TDD:
  1. Não escreva código de produção até ter um teste de unidade falhando.
  2. Não escreva mais de um teste de unidade do que o suficiente para falhar.
  3. Não escreva mais código de produção do que o suficiente para passar no teste que falhou.
• Princípios F.I.R.S.T.: Fast (Rápido), Independent (Independente), Repeatable (Repetível), Self-Validating (Auto-Validável), Timely (Oportuno).

8. Classes

• Pequenas!: Classes devem ter uma única responsabilidade (SRP).
• A Regra de Descida: Queremos que o código seja lido como uma narrativa de cima para baixo.

9. Cheiros e Heurísticas

• Rigidez: Difícil de mudar.
• Fragilidade: Quebra em muitos lugares.
• Imobilidade: Difícil de reutilizar.
• Viscosidade: Difícil de fazer a coisa certa.
• Complexidade/Repetição Desnecessária.

🛠️ Checklist de Implementação

• Esta função tem menos de 20 linhas?
• Esta função faz exatamente uma coisa?
• Todos os nomes são pesquisáveis e revelam a intenção?
• Evitei comentários tornando o código mais claro?
• Estou passando muitos argumentos?
• Existe um teste falhando para esta mudança?

Exemplo

Solicitação do usuário:

Refatore este código funcional para nomes mais claros, unidades menores, erros explícitos e comportamento preservado; verifique-o com testes focados.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.

…