Introdução

No começo da minha carreira ouvi muitas coisas sobre Clean Code, consumi dezenas de artigos e vídeos que explicavam sobre o conteúdo, mas nada foi tão esclarecedor quanto ir diretamente na fonte. Após comprar o livro e iniciar a leitura, em pouco tempo aprendi conceitos que viraram minha base de codificação.

Sempre acabo vendo pessoas criticarem as “regras” que Robert juntou neste livro, mas a verdade é que elas são alicerce de toda uma geração de desenvolvedores que já sofreram muito com códigos mal escritos.

Este é o primeiro de uma série de 3 artigos sobre o livro “Código Limpo” de Robert C. Martin, pretendo trazer um resumo do que o livro entrega na sua leitura para que seja utilizado como um guia na codificação limpa.

Press enter or click to view image in full size

Código limpo: O que é e por que é importante.

Nomes limpos de variáveis, funções limpas, classes limpas e por ai vai. Robert traz no livro um extenso conjunto de regras que ele mesmo declara como verdades absolutas. Ele traz essas regras como um conceito absoluto adquirido pela experiência como programador, são a “escola de pensamento” acerca do que seja código limpo.

Não apenas escrita de código, Bob também fala sobre como o programador limpo se comporta, tal a famosa regra do escoteiro que consiste em sempre deixar o ambiente melhor do que quando chegou, ou seja, quando você encontra um código mal escrito é seu dever refatora-lo para que se adeque aos padrões de qualidade.

Um código limpo sempre parece que foi escrito por alguém que se importava

Mesmo sendo um livro de 2009, já no começo é dito algo bem atual. O autor satiriza da ideia que não devemos mais nos preocupar com código, pois a maioria dele será gerado por ferramentas externas (essa ideia é ainda mais forte hoje em dia por conta de IAs generativas). Como o próprio Robert afirma: “Bobagens!”. Nunca nos livraremos do código enquanto trabalharmos como desenvolvedores, por mais que o nível de abstração aumente, no fundo sempre será um código de baixo nível que a máquina terá que executar. Por conta disso é essencial estar alinhados a boas práticas e escrever código de qualidade.

Princípios Básicos

O Clean Code vem com o propósito de nos fazer escrever código que seja simples e claro. Mas por que isso é necessário? Antes de querer falar sobre a solução precisamos entender o problema.

Bob traz no primeiro capítulo um tópico destinado apenas aos efeitos do código ruim. Cita uma empresa que no final de 1980 criou um app que fez muito sucesso, mas que com o tempo as atualizações ficaram com intervalos cada vez mais longos à medida que problemas do aplicativo também apareciam. Anos depois o autor teve a oportunidade de conversar com um dos funcionários dessa empresa, o qual contou que o principal motivo do fim do aplicativo foi que pela pressão de entregas frequentes a qualidade do código ficou para segundo momento. Isso fez com que o código só piorasse até que por fim ficou inviável novas alterações.

O custo de ter um código confuso é alto! Com certeza você já teve seu trabalho atrasado por se deparar com um código mal feito. Você acaba perdendo tempo tentando entender a lógica daquele código e cada alteração passa a ser muito custosa visto que as coisas vão perdendo o sentido. Essa situação é relativamente comum, até que em determinado momento todos na equipe se veem obrigados a construir um novo código, gerando custos altos.

Mas essa situação começa por conta de nós programadores que muitas vemos cedemos a pressão de entregas rápidas, comprometendo a qualidade. Se um paciente pedir para um médico não lavar as mãos antes de uma cirurgia, ele vai? Com certeza não, pois o compromisso dele é te proteger. Da mesma forma devemos proteger o código, prazos e requisitos são responsabilidades do gerente. No final das contas o código bem feito é o que realmente vai importar.

Mas então como não cair nessa armadilha e escrever boas linhas de código? É isso que o livro traz para o leitor. A prática da codificação limpa requer disciplina e sensibilidade, o desenvolvedor deve não apenas enxergar quando um código está mal escrito como deve sempre enxergar alternativas para melhorar a qualidade.

Nomenclatura: Boas práticas para nomear variáveis, funções e classes.

Uma das regras mais básicas, mas que infelizmente ainda causam problemas no dia a dia de um desenvolvedor está relacionado a nomenclatura. Você provavelmente já se deparou com nomes de variáveis, classes ou métodos em que você precisou investigar para descobrir do que se tratava.

Bons nomes devem ser descritivos, pronunciáveis e fáceis de entender. Bob destaca que o nome de uma variável, método ou classe deve comunicar sua intenção de forma clara e sem ambiguidades. Quando um nome é bem escolhido, ele reduz drasticamente a necessidade de comentários explicativos.

**Variáveis:
**Devem ter nomes descritivos. Evite abreviações genéricas como temp, data ou value, a menos que o contexto seja claro. Variáveis booleanas, por exemplo, devem soar como uma afirmação verdadeira ou falsa: isValid, hasPermission, canExecute.

**Métodos:
**Os nomes de métodos devem indicar uma ação. Alguns bons exemplos são: calculateTotal(), sendEmail() ou validateInput(). Métodos devem ser verbos ou frases verbais, deixando claro o que está sendo feito.

**Classes:
**Nomes de classes devem ser substantivos ou frases nominais, como UserService, InvoiceGenerator ou EmailClient. O nome de uma classe deve refletir sua responsabilidade principal. Se for difícil encontrar um bom nome, é um indício de que a classe pode estar fazendo mais do que deveria.

**Evite ruídos:
**Evite prefixos ou sufixos genéricos como Manager, Data, Info e Object, pois raramente isso agrega valor ao nome. Eles tornam o código mais verboso sem melhorar a compreensão. Prefira nomes simples e significativos.

**Use nomes consistentes:
**Mantenha um padrão na nomenclatura ao longo do projeto. Se você usa get para obter valores, use sempre get, não misture com fetch, retrieve, etc., a menos que haja uma diferença clara entre os termos.

**Contexto é importante:
**Quando necessário, inclua contexto no nome. Por exemplo, address pode ser vago, mas shippingAddress ou billingAddress tornam o propósito claro.

Press enter or click to view image in full size

Exemplo de nomenclaturas ruins

Press enter or click to view image in full size

Exemplo de boas nomenclaturas

Formatação: Dicas para garantir que o código seja visualmente acessível e legível

A maneira como o código é formatado influencia diretamente na sua legibilidade. Mesmo um código bem escrito pode se tornar difícil de entender se estiver mal organizado. Robert dedica um capítulo a esse tema, reforçando que o código deve ser lido como um texto bem estruturado.

**Organize o código em blocos coesos:
**Métodos relacionados devem estar próximos uns dos outros. Variáveis devem ser declaradas próximas de onde são usadas. Isso facilita a leitura e compreensão do código.

**Deixe espaço para respirar:
**Espaços em branco são importantes para separar conceitos. Eles ajudam o olho a identificar seções diferentes dentro do código. É bom separar declarações de variáveis da lógica de negócio ou blocos if/else de chamadas de métodos.

Use linhas em branco para separar visualmente blocos de lógica, mas sem exageros. Poucas linhas podem deixar o código “colado” e difícil de escanear.

**Indentação consistente:
**Manter uma indentação é conceito obrigatório. Ela estrutura visualmente a hierarquia do código, especialmente em blocos if/else, laços e métodos aninhados. A falta de padrão na indentação dificulta a leitura e aumenta o risco de erros.

**Tamanho de linha controlado:
**Linhas muito longas exigem rolagem lateral e dificultam a leitura. Se um comando ou chamada de método for muito longo, quebre-o de forma legível, mantendo a indentação clara.

**Funções curtas e focadas:
**Uma função longa normalmente é um indício de que ela está fazendo mais do que deveria. Manter funções curtas facilita a formatação e torna o código mais legível. O ideal é que cada função tenha um propósito único e bem definido.

**Consistência é mais importante que estilo:
**Mesmo que a equipe opte por um estilo de formatação específico, o mais importante é que ele seja seguido de forma consistente por todo o projeto. Formatadores automáticos ajudam a manter esse padrão. A formatação não deve ser tratada como um detalhe superficial. Um código bem formatado transmite organização, facilita manutenções futuras e reduz o tempo de entendimento.

Press enter or click to view image in full size

Exemplo de formatação ruim

Exemplo de boa formatação

Comentários: Quando escrever e quando evitar

Comentários são frequentemente visto nos códigos como um "ajudante", mas eles devem ser usados com cuidado. O próprio código deve ser claro o suficiente para dispensar a necessidade de comentários para explicá-lo.

**Comentários úteis explicam por quê, não o quê:
**Um comentário bom não descreve o que o código faz, mas sim o porquê de ele estar sendo feito daquele jeito. Por exemplo, em vez de comentar "// incrementa o contador", é melhor escrever "// necessário para evitar falha na verificação da próxima etapa".

**Evite comentários redundantes:
**Comentários que apenas repetem o que já é claro no código são inúteis e poluem visualmente o arquivo. Se um método se chama calculateInvoiceTotal(), não tem por que comentar “// calcula o total da fatura”.

**Comentários envelhecem mal:
**Diferente do código, que pode ser refatorado e testado, comentários não geram erro quando estão desatualizados , o que pode gerar confusão em quem estiver lendo. Um comentário incorreto é pior do que nenhum.

**Prefira código autoexplicativo:
**Seu objetivo deve ser escrever código tão claro que não precise de comentários. Isso pode ser feito através de nomes descritivos, estruturas bem definidas e funções pequenas. Quando o código se explica por si só, o comentário se torna desnecessário.

**Comentários legais e informativos:
**Existem situações em que o comentário é realmente valioso, alguns exemplos são:

  • Justificativas para decisões complexas ou não óbvias.
  • Avisos sobre consequências colaterais ou limitações temporárias.
  • Documentação pública de bibliotecas ou APIs.

**Evite comentários como solução para má estrutura:
**Se você sente que precisa comentar muito, talvez o problema esteja na organização ou nomeação do código. Nestes casos, refatorar costuma ser uma solução melhor do que escrever um comentário.

**Comentários TODO, FIXME e similares:
**Podem ser úteis para sinalizar pontos de melhoria, mas devem ser tratados como temporários. Comentários do tipo "// TODO: melhorar isso depois" precisam ser monitorados e resolvidos o quanto antes.

Press enter or click to view image in full size

Exemplo de comentários ruins

Press enter or click to view image in full size

Exemplo de bons comentários

Conclusão

A codificação limpa é um tema essencial dentro do desenvolvimento de software, é comum encontrar perguntas sobre isso até mesmo em entrevistas de emprego. Escrever código limpo demonstra maturidade profissional e respeito pelo trabalho, faz com que seu código não apenas funcione, mas seja compreensível, fácil de manter e elegante. Um código limpo comunica intenção, facilita revisões, reduz erros e gera confiança entre os membros da equipe.

Neste primeiro artigo exploro os fundamentos da codificação limpa, abordando os princípios básicos e três tópicos importantes: nomenclatura, formatação e comentários. Esses conceitos formam a base para um código que “fala por si” e facilita a compreensão de quem quer que o leia.