Clean Code

1. Escreva código limpo que seja legível e sustentável

A única medida válida da qualidade do código: WTFs/minuto

A legibilidade é primordial. Código limpo deve ser facilmente compreendido por outros desenvolvedores. Deve ser simples, elegante e livre de desordem. Esforce-se para escrever código que expresse claramente sua intenção sem a necessidade de comentários extensivos. Use nomes de variáveis e funções significativos, mantenha as funções pequenas e focadas, e organize o código de forma lógica.

A sustentabilidade permite a evolução. Código difícil de alterar torna-se um passivo. Projete seu código para ser flexível e modular, de modo que possa se adaptar a requisitos em mudança. Siga princípios como DRY (Don't Repeat Yourself) e SOLID para criar sistemas fracamente acoplados e altamente coesos. Refatore sem piedade para melhorar a estrutura do código sem alterar o comportamento.

Código limpo compensa. Embora escrever código limpo exija mais esforço inicial, economiza tempo e dores de cabeça significativas a longo prazo. Código limpo é mais fácil de depurar, estender e manter. Permite que os desenvolvedores trabalhem de forma mais eficiente e reduz o risco de introduzir bugs durante as mudanças. Faça do código limpo uma parte central da sua prática de desenvolvimento.

2. Siga convenções de nomenclatura significativas

O nome de uma variável, função ou classe deve responder a todas as grandes perguntas. Deve dizer por que existe, o que faz e como é usada.

Use nomes que revelem a intenção. Escolha nomes que transmitam claramente o propósito e o comportamento de variáveis, funções e classes. Evite nomes de uma única letra ou abreviações crípticas. Use nomes pronunciáveis que possam ser facilmente pesquisados. Por exemplo:

• Ruim: d (tempo decorrido em dias)
• Bom: tempoDecorridoEmDias

Seja consistente e preciso. Use convenções de nomenclatura consistentes em todo o seu código. Seja preciso para evitar ambiguidades - por exemplo, use distinções significativas como obterContasAtivas() e obterInformacoesContaAtiva(). Evite codificações ou prefixos que adicionem ruído sem valor. Nomes de classes devem ser substantivos, nomes de métodos devem ser verbos.

O comprimento do nome deve corresponder ao escopo. Use nomes mais longos e descritivos para variáveis e funções com escopos maiores. Nomes curtos são aceitáveis para escopos pequenos e locais. O comprimento de um nome deve ser proporcional ao seu escopo de uso. Otimize para legibilidade e compreensão dentro do contexto onde o nome é usado.

3. Mantenha as funções pequenas e focadas

Funções devem fazer uma coisa. Devem fazer bem. Devem fazer apenas isso.

Pequeno é bonito. Funções devem ser pequenas - tipicamente de 5 a 10 linhas. Devem caber em uma tela e ser instantaneamente compreensíveis. Extraia código em funções auxiliares bem nomeadas em vez de escrever funções longas e complexas. Funções pequenas são mais fáceis de entender, testar e manter.

Faça uma coisa bem. Cada função deve ter um propósito único e claro. Se uma função está fazendo várias coisas, extraia essas partes em funções separadas. Sinais de que uma função está fazendo muito incluem:

• Múltiplos níveis de abstração
• Múltiplas seções ou blocos de código
• Numerosos parâmetros

Mantenha um nível de abstração. As instruções dentro de uma função devem estar todas no mesmo nível de abstração. Não misture lógica de alto nível com detalhes de baixo nível. Extraia operações de nível inferior em funções separadas. Isso melhora a legibilidade, mantendo as funções focadas e conceitualmente simples.

4. Pratique formatação e organização adequadas

A formatação do código é sobre comunicação, e a comunicação é a primeira ordem de negócios do desenvolvedor profissional.

Formatação consistente importa. Use indentação, quebras de linha e espaçamento consistentes em todo o seu código. Isso melhora a legibilidade e reduz a carga cognitiva. Concorde com padrões de formatação com sua equipe e use ferramentas automatizadas para aplicá-los. Diretrizes chave de formatação incluem:

• Indentação adequada
• Colocação consistente de chaves
• Quebras de linha lógicas
• Espaçamento apropriado

Organize o código logicamente. Agrupe código relacionado e separe código não relacionado. Use linhas em branco para criar "parágrafos" entre seções lógicas. Coloque funções relacionadas próximas umas das outras. Mantenha arquivos focados em um único conceito ou componente. Divida arquivos grandes em menores e mais focados quando apropriado.

Siga convenções padrão. Adira às convenções padrão para sua linguagem e comunidade. Isso torna seu código mais familiar e acessível para outros desenvolvedores. Por exemplo, em Java:

• Nomes de classes usam PascalCase
• Nomes de métodos usam camelCase
• Constantes usam ALL_CAPS

5. Gerencie dependências e evite duplicação

A duplicação pode ser a raiz de todo mal no software.

Elimine a duplicação. Código duplicado é uma oportunidade perdida para abstração. Quando você vê duplicação, extraia o código comum em uma função ou classe reutilizável. Isso melhora a sustentabilidade centralizando a lógica e reduz o risco de mudanças inconsistentes. Tipos de duplicação a observar:

• Blocos de código idênticos
• Algoritmos semelhantes com variações ligeiras
• Cadeias repetidas de switch/case ou if/else

Gerencie dependências com cuidado. Minimize dependências entre módulos para reduzir o acoplamento. Use injeção de dependência e inversão de controle para tornar o código mais modular e testável. Siga o Princípio da Inversão de Dependência - dependa de abstrações, não de concretizações. Isso torna seu código mais flexível e fácil de alterar.

Use o princípio do menor conhecimento. Um módulo não deve conhecer os detalhes internos dos objetos que manipula. Isso reduz o acoplamento entre módulos. Por exemplo, use a Lei de Demeter - um método deve chamar apenas métodos em:

• Seu próprio objeto
• Objetos passados como parâmetros
• Objetos que cria
• Seus objetos componentes diretos

6. Lide com erros de forma graciosa

O tratamento de erros é importante, mas se obscurece a lógica, está errado.

Use exceções em vez de códigos de erro. Exceções são mais limpas e não poluem a lógica principal do seu código. Elas permitem que o tratamento de erros seja separado do caminho feliz. Ao usar exceções:

• Crie mensagens de erro informativas
• Forneça contexto com exceções
• Defina classes de exceção com base nas necessidades do chamador

Não retorne null. Retornar null leva a exceções de ponteiro nulo e polui o código com verificações de null. Em vez disso:

• Retorne coleções vazias em vez de null para listas
• Use o padrão Null Object
• Use Optional em Java ou Maybe em linguagens funcionais

Escreva declarações try-catch-finally primeiro. Comece com o try-catch-finally ao escrever código que pode lançar exceções. Isso ajuda a definir o escopo e as expectativas para o código chamador. Garante que os recursos sejam gerenciados e liberados adequadamente, mesmo em cenários de erro.

7. Escreva testes unitários completos

Código de teste é tão importante quanto código de produção.

Siga as três leis do TDD. Desenvolvimento Orientado a Testes (TDD) melhora a qualidade e o design do código:

1. Escreva um teste falho antes de escrever qualquer código de produção
2. Escreva apenas o suficiente do teste para demonstrar uma falha
3. Escreva apenas o suficiente de código de produção para passar no teste

Mantenha os testes limpos e sustentáveis. Aplique os mesmos padrões de qualidade de código aos seus testes que ao seu código de produção. Refatore e melhore o código de teste regularmente. Testes bem estruturados servem como documentação e permitem refatoração sem medo do código de produção.

Almeje uma cobertura de teste abrangente. Escreva testes que cubram casos extremos, condições de limite e cenários de erro - não apenas o caminho feliz. Use ferramentas de cobertura de código para identificar lacunas na cobertura de teste. Lembre-se de que 100% de cobertura não garante código livre de bugs, mas proporciona confiança na refatoração e nas mudanças.

8. Refatore o código continuamente

Deixe o acampamento mais limpo do que o encontrou.

Refatore oportunisticamente. Melhore a estrutura do código sempre que trabalhar em uma parte do código. Siga a Regra do Escoteiro: deixe o código melhor do que o encontrou. Pequenas melhorias incrementais se somam ao longo do tempo e previnem a deterioração do código. Técnicas comuns de refatoração incluem:

• Extração de métodos ou classes
• Renomeação para clareza
• Simplificação de condicionais complexas
• Remoção de duplicação

Refatore com segurança usando testes. Sempre tenha uma suíte sólida de testes antes de refatorar. Faça mudanças pequenas e incrementais e execute os testes frequentemente. Isso lhe dá confiança de que suas mudanças não estão quebrando a funcionalidade existente. Use ferramentas automatizadas de refatoração quando disponíveis para reduzir o risco de introduzir erros.

Equilibre a refatoração com a entrega de valor. Embora a refatoração contínua seja importante, não deixe que ela paralise o progresso. Almeje o "bom o suficiente" em vez da perfeição. Foque os esforços de refatoração nas áreas mais problemáticas ou frequentemente alteradas do código. Comunique o valor da refatoração aos stakeholders para garantir o suporte à melhoria contínua do código.

9. Aplique princípios de programação orientada a objetos e funcional

Objetos escondem seus dados por trás de abstrações e expõem funções que operam nesses dados. Estruturas de dados expõem seus dados e não têm funções significativas.

Use princípios orientados a objetos com sabedoria. Aplique princípios como encapsulamento, herança e polimorfismo para criar designs flexíveis e modulares. Siga os princípios SOLID:

• Princípio da Responsabilidade Única
• Princípio Aberto-Fechado
• Princípio da Substituição de Liskov
• Princípio da Segregação de Interfaces
• Princípio da Inversão de Dependência

Aproveite conceitos de programação funcional. Mesmo em linguagens orientadas a objetos, técnicas de programação funcional podem levar a um código mais limpo:

• Funções puras sem efeitos colaterais
• Dados imutáveis
• Funções de ordem superior
• Composição de funções

Escolha a abordagem certa para o problema. Paradigmas orientados a objetos e funcionais têm pontos fortes e fracos. Use design orientado a objetos quando precisar modelar domínios complexos com comportamento. Use abordagens funcionais para transformação de dados e pipelines de processamento. Muitas linguagens modernas suportam uma abordagem híbrida, permitindo que você use a melhor ferramenta para cada parte do seu sistema.

10. Considere a concorrência com cuidado

A concorrência é uma estratégia de desacoplamento. Ajuda-nos a desacoplar o que é feito de quando é feito.

Entenda os desafios da concorrência. Programação concorrente introduz complexidade e potencial para bugs sutis. Problemas comuns incluem:

• Condições de corrida
• Deadlocks
• Sinais perdidos
• Problemas de visibilidade de memória

Separe as preocupações de concorrência. Mantenha seu código relacionado à concorrência separado do restante do código. Isso torna mais fácil raciocinar e testar. Use abstrações como Executors, Futures e Actors para gerenciar a concorrência em vez de trabalhar com threads brutas.

Prefira imutabilidade e funções puras. Objetos imutáveis e funções puras são inerentemente thread-safe. Eles eliminam muitos problemas de concorrência ao evitar estado mutável compartilhado. Quando o estado mutável é necessário, use técnicas de sincronização adequadas e considere usar variáveis atômicas ou coleções concorrentes.

Última atualização: January 22, 2025