3 dicas para nomear variáveis: como dar nome a variáveis like a pro

Nomear variáveis tem suas técnicas e boas práticas; uma tarefa tão simples quanto dar nome a variáveis pode guardar muitos segredos, muitas técnicas para que o código fique muito mais profissional e muito mais eficiente.

Saber nomear variáveis vai proporcionar uma excelente leitura de código para todos os colegas devs que, no futuro, vão ler aquele código, e até para você mesmo, depois de um tempo sem mexer naquele projeto, quando voltar àquele código que escrever, vai perceber que as coisas ficam muito mais fáceis.

Acredite ou não, mas nomear variáveis corretamente até aumenta a qualidade de seu código e sua produtividade e rendimento como desenvolvedor, já que fica mais fácil ler e entender o código feito — e, como sabemos, nós, devs, passamos muito mais tempo lendo códigos do que escrevendo.

1. O nome da variável deve descrever a entidade que representa

A primeira dica para nomear variáveis é: “Um nome de variável deve descrever a entidade que representa“, ou seja, ele tem que ser auto descritivo.

Por exemplo, uma variável chamada “value” com valor “dpw”, pode até funcionar, mas é um nome de variável que não descreve a entidade que representa.

Outro exemplo muito comum também é, por exemplo, “let val”, ao invés de “value”, mas, novamente, não descreve a entidade que ele representa; não é auto-descritivo.

Então, seria muito dar o seguinte a esta variável: “blogName”. Aqui sim ele é auto-descritivo; num só golpe de vista é possível entender do que se trata e ele recebe seu valor. Está muito melhor.

Outro exemplo: “let number = 20”. Tudo bem, é um número, mas o quê, exatamente, é esse número? É isso, esse tipo de descrição, esse tipo de informação auto descritiva que se busca conseguir com uma boa nomenclatura de variáveis.

Então, em vez de “number”, dentro de um exemplo fictício, poderia ser algo como “daysSinceCreation”, alguma coisa assim, “dias desde que foi criado”, que é um nome totalmente descritivo, muito diferente de somente “number”.

Exceções: padrões já usados e conhecidos da comunidade

Claro que podem existir algumas exceções, por exemplo, convenções de loop. Então, vamos fazer um loop. É muito comum colocar, por exemplo, a letra “i”. Então, nesse caso, não teria problema. É uma convenção da comunidade, é algo que a maioria dos desenvolvedores entende (se não, todos) e não tem problema.

E, claro, aqueles loops dentro de loops, pode ser o “i”, “j”, “k”, enfim, dá para ser usado dessa maneira porque são pontos bem específicos, pontos de código bem específicos, bem conhecidos pela comunidade, e que não atrapalha em nada no entendimento do código.

Outra exceção pode ser em definições de eventos com .addEventListener(). É bastante comum na comunidade uma convenção de dar o nome do parâmetro de evento (event) como “e” ou “ev”:

No caso de padrões bem consagrado da comunidade, não tem problema. Se preferir, pode colocar o próprio “event”, claro, mas este seria um caso de exceção em que um nome de variável abreviado não causaria maiores problemas no código.

Cuidados com booleanos ao nomear variáveis

Algo interessante, também, é a respeito de booleanos. Os nomes de variáveis booleanas podem ser dados de várias maneiras, mas existem alguns macetes que ajudam a melhorar bastante a qualidade do código.

Estes nomes, por exemplo:

São booleanos que podem ter seus nomes melhorados de maneira simples; melhorias na qualidade do código que podem ser feitas com a adição de poucos caracteres:

Essas palavrinhas “is”, “are”, “has” e similares deixam a leitura muito mais fácil, clara e eficiente e, variáveis com tal nível de qualidade ajudam bastante quando forem usadas futuramente no código.

Abordagem “positiva”

Outra dica para dar nomes a variáveis é preferir uma abordagem “positiva” na hora de dar seus nomes ao invés de uma abordagem “negativa”.

Por exemplo:

Perceba que fica difícil até na hora de fazer a lógica usando essas variáveis, não só de ler, como pensar no quê deve ser feito. Então, ao invés de “isInvisible = false” ou “hasNoEncryption = false”, prefira a abordagem positiva:

2. Ao escrever o código, priorize a facilidade de leitura, não a de escrita

O segundo princípio para nomear bem variáveis é algo que já se deduz das dicas anteriores: “Ao escrever o código, priorize a facilidade de leitura, não a de escrita“.

Passamos muito mais tempo lendo o código do que escrevendo, então, ao escrever o código, priorize a facilidade de leitura e não a descrita.

Basicamente, é uma espécie de extensão do princípio anterior, para a coisa ser mais auto descritiva, para não gerar confusões, não gerar dúvidas, e a sua leitura (e a de seus colegas, no futuro) ficar muito mais simples, muito mais fácil.

Então, por exemplo, a gente pode ter uma definição de variável let h = 16. Você lê o código e consta “h = 16”, mas o que seria esse “h”, o que significa? É bastante comum, inclusive, a definição vir acompanhada de um comentário:

Na verdade, isso é bastante comum de se encontrar na nomenclatura de variáveis, mas é muito prejudicial à qualidade do código e, consequentemente, futura leitura do mesmo.

Escolher letras únicas como nome de variável (ou abreviaturas), quando usadas em declarações, loops e lógica, acaba prejudicando bastante, pois as pessoas (incluindo quem escreveu) acabam não entendendo muito do que se trata.

Não seria muito melhor ser auto descritivo? Não seria muito melhor priorizar a facilidade de leitura? Então, em vez de “h” com um comentário, seria possível refatorar isso para algo como:

Fica um pouquinho maior, mas esse nome de variável é muito mais descritivo e não vai causar nenhuma dúvida. Além do mais, dessa forma, foi possível eliminar o comentário, já que o próprio código se comenta, por assim dizer.

Um outro exemplo, dessa vez com abreviatura:

Quando algo assim consta no código, no momento de escrever uma lógica, quando é preciso colocar num código mais rebuscado, pode acontecer de se esquecer o significado da variável, porque, além dessa abreviatura, vão ter outras, então, é muito mais simples colocar algo como:

Que é um código que já informa exatamente o que é aquele valor. Também neste caso é possível dispensar o comentário e o código ficou descritivo e priorizado para facilidade de leitura, em detrimento à facilidade de escrita.

Só um último exemplo, então: a gente pode colocar aqui… Então, o cara colocou essa variável aqui, futuramente, para receber um valor, mas o que significa isso? Que coisa esquisita,
que coisa que não dá para entender o que é, do que se trata… Não seria muito mais fácil colocar “generatedTimestamp”? Agora, deu para entender o que é, né?

Dicas bônus do livro “Código Limpo”

O livro Código Limpo — também muito conhecido por seu nome original Clean Code — foi escrito por uma sumidade na área da programação, Robert Martin, mais conhecido como Uncle Bob (você já deve ter ouvido falar nele), e é um absoluto clássico entre devs que querem aprimorar suas técnicas e escreverem códigos mais profissionais.

Do Código Limpo, podemos tirar uma excelentes dicas para nomear variáveis: “Escolha nomes descritivos e inequívocos“. Para isso, é possível fazer 3 perguntas no momento de escolher o nome para a variável:

1. Por que existe?
2. O que faz?
3. Como é usada?

Outra: “Os nomes de variáveis devem ser pronunciáveis“. Olha que dica legal. Pelos exemplos que a gente viu até agora, aquelas abreviaturas, aquelas letras únicas, aquelas confusões, que, geralmente, a gente encontra pelos códigos, os nomes não são pronunciáveis.

Quando você vai até conversar com um colega, você consegue sequer dizer o que é o nome daquela variável; você não consegue pronunciá-lo. Então, é interessante que os nomes sejam pronunciáveis.

E mais uma dica é: “Os nomes devem ser pesquisáveis“. A partir do momento que ele é pronunciável, ele também é pesquisável, então, quando você precisa fazer uma busca sobre determinada variável, ao invés de você ter que lembrar daquela abreviação, daquela letra única, você sabe o nome da variável, ou, pelo menos, alguma palavra que a forma, e você consegue fazer uma busca por essa variável.

3. Use padrões consistentes em todo o projeto

Essa dica pode ter vários sentidos, vários significados, mas a ideia-base é adotar padrões consistentes em todo projeto, no sentido daquela máxima conhecida na programação: é melhor tomar grandes decisões globais únicas que pequenas decisões locais a todo momento.

Isso pode ter alguns significados possíveis. O primeiro deles é a respeito da notação de variáveis que é usada no projeto. Existem diversas notações possíveis:

• camelCase
• PascalCase
• snake_case
• kebab-case
• CONSTANT
• etc.

Lembrando o seguinte: veja, também, as convenções da linguagem de programação que você está usando; às vezes, determinada linguagem tem como boa prática usar um “camel case” ou usar um “pascal case”.

Então, adote uma notação, não importa qual seja — desde que esteja consonante à linguagem que você está usando e, preferencialmente, que seja um padrão do comunidade.

Ao nomear variáveis, evite a notação húngara

A chamada notação húngara adiciona determinados prefixos ou sufixos ao nome da variável para identificar seu respectivo tipo.

Por exemplo: uma variável name se torna strName (“str” de string); number se torna arrNumber (“arr” de array) e; assim por diante.

Geralmente, é bom que a notação húngara seja evitada. Pode ter um ou outro caso que é exceção, mas, regra geral, é bom evitar, então, só o que você colocaria, mesmo, continuando com os exemplos, seria name,
numbers e assim por diante.

No futuro, esse tipo de dado pode se alterar e aí o código vai ficar desatualizado; você vai ter que alterá-lo para corresponder ao novo tipo e coisas assim.

Se você estiver lidando com uma linguagem mais “tipada”, isso pode até ser minimizado, mas pode influenciar (mesmo em linguagens assim) no nome da variável. Então, evite usar a notação húngara.

De qualquer maneira, ela já está praticamente em desuso e quase ninguém a tem visto em linguagens Web mais recentes. E isso tem seus motivos para isso acontecer.

Não use sinônimos ou equivalentes para se referir às mesmas coisas

Não use a mesma palavra para diferentes conceitos nem se refira ao mesmo conceito através de diferentes palavras.

Explicando melhor através de um exemplo, veja essas 3 declarações de variável:

Perceba que essas 3 variáveis aparecendo em um mesmo código são ambíguas; não há muita diferença, nesse contexto, em se nomear a variável para complementar “product” de “Data”, “Info” ou “Details”; são conceitos bem próximos.

Defina somente 1 desses conceitos — por exemplo, “productDetails” — e use o que foi decidido no restante do tempo que for tratar daqueles detalhes de produto.

Um outro exemplo, para ficar mais claro:

Veja que “returned”, “fetched” e “retrieved” são conceitos muito próximos, muito equivalentes, que podem gerar confusão se vistos uns próximos dos outros. Então, mais uma vez, escolha um, por exemplo, “retrievedFruits”, e se atenha a esse padrão, usando-o no restante do tratamento que você dá a isso daqui no código.

Conclusão

Como visto, uma tarefa tão simples quanto dar nome a variáveis pode guardar muitos segredos, muitas boas práticas, muitas técnicas para que o código fique muito mais profissional e muito mais eficiente.

Muitas dessas dicas podem ser “extraídas” da experiência em lidar com diferentes projetos, mas, felizmente, a maioria já está documentada em livros de excelente qualidade, com o Código Limpo, artigos de blog etc.

Mas qual é a sua dica para nomear variáveis? Qual é a boa prática que você indica, a sua técnica, a sua boa tática para nomear variáveis? Coloque nos comentários, que a gente quer saber!