Código Limpo: Dicas e Estratégias para Escrever Código de Qualidade

O termo “Código limpo” é usado para descrever código fonte que é fácil de ler, entender e manter. Segundo Michael Feathers, um código limpo sempre parece que foi escrito por uma pessoa que se importava com ele.

O conceito de código limpo foi popularizado pelo livro “Clean Code: A Handbook of Agile Software Craftsmanship” de Robert C. Martin. Segundo ele, a redução de duplicação de código, a alta expressividade (código simples e direto) e a criação de abstrações simples no início, são as ações que tornam um código limpo.

De forma a conseguir aplicar esse conceito na prática, neste artigo, serão abordados os seguintes temas:

• Como criar nomes significativos?
• Funções
• Classes
• Comentários
• Formatação

Como Criar Nomes Significativos?

_{Adão atribuindo nomes aos animais.}

• Use nomes que revelem seu propósito. O nome de uma variável, função ou classe deve responder a todas as grandes questões. Ele deve dizer porque existe, o que faz e como é usado.
• Evite informações erradas. Os programadores devem evitar passar dicas falsas que confundam o sentido do código. Devemos evitar palavras cujos significados podem se desviar daquele que desejamos.
• Faça distinções significativas. Faça a distinção dos nomes de forma a que o leitor compreenda as diferenças.
• Use nomes pronunciáveis. Um exemplo de um nome não pronunciável é, por exemplo, “private Date genymdhms”.
• Use nomes passíveis de busca. Nomes longos se sobressaem aos pequenos e qualquer nome passível de busca se sobressai a uma constante no código. Se usar nomes pequenos, que eles sejam claros.
• Atente nos prefixos de variáveis. Quanto mais lemos o código, menos prefixos enxergamos. No final, estes se tornam partes invisíveis e um indicativo de código velho.
• Evite o mapeamento mental. Uma diferença entre um programador esperto e um programador profissional é que este entende que clareza é fundamental. Os profissionais se preocupam em escrever código que outros possam entender, por outras palavras, código limpo.
• Escolha bem os nomes de classes. Classes e objetos devem ter nomes com substantivo(s).
• Cuide dos seus nomes de métodos. Os nomes de métodos devem ter verbos.
• Opte pela clareza no lugar do divertimento. Os programadores saberão o que deve fazer a função HolyHandsGrenade? Claro, é engraçado, mas talvez DeleteItems seja mais fácil de entender.
• Selecione uma palavra por conceito. Um léxico consistente é uma grande vantagem para os programadores que precisam usar seu código.
• Não faça trocadilhos. Evite usar a mesma palavra para dois propósitos. Usar o mesmo termo para duas ideias diferentes é basicamente um trocadilho.
• Adicione um contexto significativo. Há poucos nomes que são significativos por si só – a maioria não é. Por conta disso, você precisa usar nomes que façam parte do contexto para o leitor. Para isso você os coloca em classes, funções e namespaces bem nomeados.

Funções

A primeira regra para funções é que elas devem ser pequenas, algo em torno de 20 linhas no máximo.

As funções devem fazer apenas uma coisa e devem fazê-la bem. Uma forma de saber se uma função faz mais de “uma coisa” é se você extrair outra função dela a partir de seu nome que não seja apenas uma reformulação de sua implementação.

As funções devem fazer ou responder algo, mas não ambos. Sua função ou altera o estado de um objeto ou retorna informações sobre ele. Efetuar as duas tarefas costuma gerar confusão.

Parâmetros de Funções

A quantidade ideal de parâmetros para uma função é zero. Depois vem um, seguido de dois. Sempre que possível deve evitar três parâmetros.

Parâmetros Lógicos

Esses parâmetros são feios. Passar um booleano para uma função certamente é uma prática horrível, pois ela complica imediatamente a assinatura do método, mostrando explicitamente que a função faz mais de uma coisa. Ela faz uma coisa se o valor for verdadeiro, e outra se for falso. Uma alternativa ao uso dos parâmetros lógicos seria criar duas funções, uma para cada caso.

“Criar um software é como qualquer outro tipo de escrita. Ao escrever um artigo, você primeiro coloca seus pensamentos no papel e depois os organiza de modo que fiquem fáceis de ler. O primeiro rascunho pode ficar desastroso e desorganizado, então você reestrutura e refina até que ele fique como você deseja.”

Classes

A primeira regra para as classes é que devem ser pequenas e o tamanho da classe é medida conforme as suas responsabilidades. De acordo com Robert C. Martin, o nome de uma classe deve descrever quais as suas responsabilidades,  respeitar o princípio da responsabilidade única e que os nossos sistemas sejam compostos por muitas classes pequenas, e não poucas classes grandes. Cada classe pequena encapsula uma única responsabilidade, possui um único motivo para ser alterada e contribui com poucas outras para obter os comportamentos desejados no sistema.

O autor do Código Limpo afirma que temos que estruturar nossos sistemas de modo que baguncemos o mínimo possível quando os atualizarmos. Num sistema ideal, incorporaríamos novos recursos através da expansão do sistema e não alterando o código existente. Ou seja, precisamos suportar o princípio-chave de projeto de classe, conhecido como Princípio de Aberto-Fechado (OCP).

Comentários

Segundo Robert C. Martin, o uso adequado de comentários permite compensar nosso fracasso em nos expressar no código. Devemos usá-los porque nem sempre encontramos uma forma de nos expressar sem eles, mas o seu uso não é motivo de comemoração. Então, quando você estiver numa situação na qual precise criar um comentário, pense bem e veja se não há como se expressar através de código em si. De acordo com o autor do Código Limpo, quanto mais antigo um comentário for e quanto mais longe estiver do código o que ele descreve, mais provável será que esteja errado. O motivo é simples. Não é realístico que programadores consigam mantê-los atualizados. O autor afirma também que uma das motivações mais comuns para criar comentários é um mau código. Melhor do que inserir um comentário é limpar o código!

No entanto, certos comentários são necessários ou benéficos, tais como:

• Comentários legais (Relacionado ao Direito e a legislação);
• Comentários informativos;
• Comentários que explicam a intenção;
• Comentários que trazem esclarecimento;
• Alertam sobre as consequências;
• Comentários TO DO: notas deixadas no código fonte para indicar que uma determinada parte do código ainda não foi implementada ou está incompleta, mas que precisa ser trabalhada no futuro;
• Comentários para destacar a importância de algo.

Como também existem aqueles que podem ser evitados:

• Comentários redundantes;
• Comentários imperativos;
• Comentários enganadores;
• Comentários ruidosos;
• Créditos e autoria;
• Código como comentários;
• Comentários HTML;
• Comentários com conexões com o código nada óbvias.

Formatação

Para que seu código fique bem formatado, você deve escolher uma série de regras simples que governem seu código e, então, aplicá-la de forma consistente. Se estiver trabalhando em equipe, então, todos devem concordar com uma única série de regras de formatação. Atualmente, existem ferramentas automatizadas para ajudar na aplicação dessas regras.

Recomendações

• Cada linha em nosso código representa uma expressão ou uma estrutura, e cada grupo de linhas representa um pensamento completo. Esses pensamentos devem ficar separados por linhas em branco.

• Linhas de código que estão intimamente relacionadas devem aparecer verticalmente unidas. Obviamente essa regra não funciona para conceitos em arquivos separados. Mas, então, não se deve separar em arquivos distintos conceitos intimamente relacionados, a menos que tenha uma razão muito boa.

• Se uma função chama a outra, elas devem ficar verticalmente próximas, e a que chama deve ficar acima da que for chamada, se possível.

• Devemos nos esforçar para manter nossas linhas de código curtas. Segundo Robert C. Martin, “O antigo limite de 80 de Hollerith é um pouco arbitrário, e não sou contra linhas com 100 ou mesmo 120 caracteres. Mas ultrapassar isso provavelmente é apenas falta de cuidado…Eu, pessoalmente, determinei 120 como meu limite”.

Indentação

O autor do livro Código Limpo recomenda indentar o código. Segundo ele, a indentação é uma forma de tornar visível a hierarquia dos escopos, indentando as linhas do código-fonte de acordo com sua posição na hierarquia.

Código Limpo: Considerações Finais

Em suma, a clareza na escolha dos nomes para funções, métodos, classes, módulos e variáveis é crucial para a compreensão e manutenção do código. Evitar trocadilhos, dicas falsas e nomes engraçados, enquanto prioriza distinções significativas e pronunciáveis, não apenas facilita a leitura, mas também revela o propósito subjacente de cada elemento. Assim como na escrita de um artigo, onde a organização dos pensamentos resulta em clareza, a estruturação cuidadosa do código torna-o legível e, ao mesmo tempo, robusto. 

No próximo artigo, vamos abordar temas como tratamento de erros, testes de unidade e outros aspectos importantes para a busca da excelência no código limpo. Não perca!