fbpx

A importância dos nomes para um código limpo

nome

Você já deve ter perdido muito tempo tentando entender um trechos de código parecidos com esse:

var obj = SaveOrder(c, p, pinf)

Quanto tempo você precisou pensar para decifrar cada argumento do método SaveOrder?
E esse obj que guarda o retorno do método? Aposto que fez você torcer o nariz.

Veja se fica melhor agora:

var order = OrderService.Create(customer, product, paymentInfo)

Muito mais claro, não acha?

Clareza é fundamental!

Se tem uma coisa que incomoda é ler um trecho de código e não entender de imediato qual foi a sua intenção. Se uma variável precisa guardar o nome de um cliente, por quê chamá-la de nom?

Já se foi o tempo que tínhamos justificativas para nomear as coisas como se estivéssemos tentando esconder um grande segredo. Pensar em nomes de variáveis que revelam seu propósito; criar métodos que indiquem claramente qual será sua ação, sem precisar meditar sobre a infinidade de argumentos que ele recebe, tornam a vida do próximo programador que lerá o código muito mais fácil. O software fica mais fácil de manter e sua mudança se torna muito mais previsível.

A primeira coisa a saber sobre nomes é que eles devem designar propósito.

Sempre que preciso nomear algo que estou desenvolvendo, tento responder as seguintes perguntas:

Perguntas que todo programador deve se fazer antes de nomear componentes em seu programa

O nome revela seu propósito?

Se você declara um array de frutas, não caia na tentação de chamá-lo de arr, list ou items, por mais trivial que possa parecer. Crie o hábito de dar nomes claros, livre de abreviações e enigmas que só você sabe interpretar.

É nítido olhar para o trecho abaixo e identificar que do lado esquerdo do sinal de atribuição, uma variável de nome frutas acaba de receber uma coleção de frutas.

var frutas = ["Banana", "Maçã", "Uva"]

No trecho seguinte, uma estrutura de repetição faz referência à previsível variável frutas, e você vai entender, assim que bater os olhos:

for (var fruta in frutas)
{
    Console.Writeline(fruta);
}

Agora, imagine se fosse uma variável chamada arr, lst ou f. É muito provável que você se esforçaria para lembrar que a variável guarda uma coleção de frutas, que você declarou no início do código. Você teria que buscar no mapa mental escondido em algum lugar do seu cérebro o significado da tal variável de nome obscuro.

A leitura do código deve ser como se estivéssemos lendo um artigo de jornal: clara, objetiva, ordenada; com início, meio e fim. Designar bons nomes é uma das tarefas mais importantes na construção de um código limpo. Se é um array de frutas, por quê dar outro nome? Parece óbvio, mas é tão comum ver esse tipo de coisa que achei relevante comentar.

É fácil localizar?

Outro ponto que deve ser levado em conta é quanto aquilo que você nomeia pode ser facilmente encontrado.
Imagine alguém do seu time tentando encontrar um bug no código, do qual a única referência que se tem é uma terminologia do negócio?

Facilitaria muito a vida do seu colega se ele encontrasse, na primeira busca, poucas ocorrências relacionadas ao termo que estivesse tentando encontrar.

Se você precisa declarar uma constante que representa o máximo de ocorrências de uma despesa, não hesite em deixar claro o nome MAX_OCORRENCIA_DESPESAS. Por mais que parece verborrágico, é melhor que seja assim, do que simplesmente declarar MAX ou OCORRENCIAS, e, depois, seu colega se matar para peneirar, entre as infinitas ocorrências da busca, aquilo que está procurando.

Transmite informação errada?

Tome cuidado com declarações que denotem outros significados.
Recuperar pode servir tanto para corrigir quanto obter algo. O código deve expressar a clareza de um professor primário no processo de alfabetização de uma criança. Deixe sua imaginação poética e encapsulamento de sentidos para outro momento. Seu código deve ser o mais óbvio possível.

Possui referências redundantes?

Antigamente, era comum encontrar variáveis declaradas com sufixo de seu tipo para facilitar o reconhecimento do tipo de variável. Programadores muito criativos da época achavam tão estranho encontrar variáveis nomeadas como nameString, valueDecimal, ageInt, pelo código, que passaram a chamar de notação húngara.

Outra prática que deve ser evitada é dar prefixo a membros privados de classe. Entre programas escritos em c# é comum encontrar membros com prefixo “_”. Alguns defendem que o prefixo ajuda a evitar colisão de nomes entre parâmetros de métodos e membros da classe. Mas esse prefixo ruidoso não é necessário quando se pode fazer referência à instância com this.

Tem contexto significativo?

É comum encontrar membros de classe com prefixo do contexto como endDestinatario, endLogradouro, endBairro, endCidade, endCep, etc. Apesar de indicar que o grupo de variáveis faz parte de um contexto endereço, o ideal é sempre criar uma classe para representar a estrutura dos dados. Faz uma diferença tremenda delimitar contextos entre componentes do sistema.

Faz distinção significativa?

Não banque o esperto adicionando caracteres ou números aleatórios declarando variáveis como n1, n2, n3, só porque você não encontrou um bom nome. Pare, respire e pense mais um pouco até que você um nome que faça sentido apareça.

É isso…

De forma geral, essas práticas ajudam a melhorar a legibilidade do seu código.
Talvez esses sejam os primeiros passos para evitar que seu código se degrade com o tempo.
E se em algum dia este momento chegar, e seu código morrer, que morra com dignidade.

E se você gostou das dicas e quer aprender mais sobre o tema, leia o livro Clean Code do uncle Bob.
É dever de todo programador que se preocupa com qualidade de código conhecer.

Receba meu conteúdo no Telegram

Se você deseja receber outros conteúdos direto no seu celular, entre no meu canal no Telegram.
Lá eu compartilho dicas para você dominar definitivamente a escrita do código limpo.

Hey,

o que você achou deste conteúdo? Conte nos comentários.

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *