Executando verificação de segurança...
25

Como nomear melhor

No desenvolvimento, nomeamos tudo que possível, nomeamos variáveis, funções, parâmetros, classes, pacotes, arquivos fontes... A seguir listarei regras simples para a criação de bons nomes.

Use nome 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 lhe dizer por que existe, o que faz e como é usado.

Neste exemplo, fica claro que é uma variável que guarda o tempo decorrido em dias:

var elapsedTimeInDays;

Tente evitar sempre algo desse tipo:

var d;
var elpTimeD;
var elapsedTime

Veja a diferença nesses dois códigos:

function getQuantity(list1){
	var x = 0;
	list.map((val) => {
		if(val === 4) {
			x++;
		}
	})
return x;
}

Perceba que neste exemplo dá pra identificar o que a função faz, retorna a quantidade de algo. Entretanto, o que é esse algo? a lista que é passado por parâmetro guarda o que? o que significa o valor 4? Você terá que procurar no restante do código todas essas perguntas.

function getAmountApples(fruitList){
var quantityApple = 0;
var apple = 4;
	list.map((fruit) => {
		if(fruit === apple) {
			quantityApple++;
		}
	})
return quantityApple;
}

Já neste exemplo, de cara vemos que a função retorna a quantidade de maçãs de uma lista de fruta só pelas nomeação da função e parâmetros. Lembre-se, a questão aqui é nomeação.

Evite informações erradas

  • Deve-se evitar passar dicas falsa que confundam o sentido do código. Por exemplo: hp, aix, sco seriam nomes bem ruins de variáveis, pois são nomes de plataformas Unix ou variantes. Mesmo que estiver calculando uma hipotenusa, evite abreviações como hp, pois pode ser mal interpretado. Lembre-se, não é por que você entende que seu coleguinha é obrigado a entender.
  • Cuidado ao usar nome muito parecidos. Algo como nosso próximo exemplo pode acabar gerando uma troca de variáveis indesejável:
var xyzControllerForEfficientHandlingOfStrings;
var xyzControllerForEfficientStoragengOfStrings

Faça distinções significativas

  • Utilizar números sequenciais em nomes é o oposto de nomes expressivos ( listFruit1, listFruit2 ... ).
  • Utilize sempre nomes pronunciáveis, pois a leitura do código deve chegar mais próximo da leitura de um texto. Imagine ler uma variável em voz alta da seguinte forma: no bê cê erre três cê ene tê. Isso é importante, pois a programação é uma atividade social, a leitura deve ser fluida.
var noBCR3CNT;
  • Palavras muito comuns são outra forma de distinção que nada expressam, sem falar que palavras comuns são redundantes. Por exemplo: productInfo, productData. Info e Data são palavras muito comuns e vagas, não fica claro o que essas variáveis representam.

Perceba que dos 3 exemplos a seguir retrata esse erro. Qual diferença das 3 funções? Não fica claro a diferença entre elas.

function getActiveAccount();
function getActiveAccounts();
function getActiveAccountsInfo();
  • Utilize nomes passiveis de busca. Se você utilizar apenas letras, abreviações ou números, quando ocorrer uma pesquisa por essa variável, irá aparecer dezenas ou centenas de resultados não esperado. Tenha em mente que sum pode não ser prático, mas é bem melhor de fazer uma busca que s.

Evite Codificações

Já temos de lidar com bastante codificações e não precisamos acrescentar mais. Fazer isso, vai exigir tempo e esforço desnecessário na decifração.

Nomes de Classes

Classes devem ter nomes com Substantivo, como Client, PaginaWiki, Eddrees..

Nome de Métodos

Os nomes dos métodos devem ter verbos, como postarPagamento, excluirPagina ou salvar..

Selecione palavras por conceito

Escolha uma palavra por cada conceito abstrato e fique com ela. Por exemplo, é confuso ter que pegar, obter e recuperar como métodos equivalentes de Classes diferentes. Quando for utilizar, vai ficar um pouco complicado de lembrar qual método é de cada classe. Se escolher o método get, tente utilizar get em todos os métodos.

Não faça trocadilhos

Sempre evite utilizar a mesma palavra para propósitos diferentes.

Utilize nome a partir do Domínio da Solução/Solução

Lembre-se de que serão programadores que lerão seu código. Portanto, pode usar temos de Informática, nomes de algoritmos, nomes de padrões, termos matemáticos e etc. Caso não houver como expressar um desses termos ou outros termos, você poderá utilizar um nome do Domínio do problema.

Adicione um contexto significativo

Há poucos nomes que são significativos por si só, a maioria não é. Por isso, você precisa usar nomes que façam parte do contexto para o leitor. Caso a palavra/termo escolhido não dê um contexto por si só, você poderá adicionar um prefixo.
Imagine que você leu as seguintes variáveis:

const firstName = '';
const lastName = '';
const street = '';
const houseNumber = '';
const city = '';

De cara você perceberia que se trata de um conjunto de informações que constitui um endereço. Porém, se em algum contexto, uma dessas variáveis surgir sozinha, você conseguirá identificar de que se trata?

Logo, um prefixo é bem vindo nesse caso:

const addrFirstName = '';
const addrLastName = '';
const addrStreet = '';
const addrHouseNumber = '';
const AddrCity = '';

Não adicione contextos desnecessários

Em uma aplicação que você esteja trabalhando chamada “Gas Station Deluxe” (GSD), seria uma péssima ideia adicionar prefixos a toda classe com GDS. Para ser sincero, você estaria trabalhando contra suas ferramentas. Quando você digitar G e pressionar a tecla de autocompletar, aparecerá uma lista grande de classes e métodos iniciando com a letra G.

O mais difícil sobre escolher bons nomes é a necessidade de se possuir boas habilidades de descrição e um histórico cultural compartilhado. Essa é uma questão de aprender.

Não sinta receio de renomear o código por temer que os outros desenvolvedores sejam contra. Quando o condigo muda para melhor, todos ficam agradecidos.

Esse resumo baseado no livro Clean Code
Martin R.C.; Michael C.F.; Timothy R.O. Titulo: Clean Code.

Carregando publicação patrocinada...
3

Clean Code é vida, dá até gosto quando navegamos por um código e o nome da variável é tão explicito que automaticamente você já associa o que aquela função está executando.

Quando estou codando, geralmente tenho dificuldade de criar nomes bons. Uma dica que sempre me ajuda é pensar no verbo/substantivo relacionado ao contexto do que está sendo criado.


Exemplo 1:

Aqui sei que estou buscando por todos os usuários.
const fetchAllUsers = () => ...

Aqui sei que estou buscando por um usuário pelo id.
const fetchUserById = (id) => ...

Nessas duas funções, o verbo é o mesmo, pois a ação é a mesma. Mas pelo substantivo ser no plural e outro no singular, já começa me indicar que fazem coisas diferentes...


Exemplo 2:

Aqui está executando uma busca, mas pelo quê?
const fetchAll = () => ...

Aqui está executando uma busca pelo id, mas do quê?
const fetchById = (id) => ...

Nesse segundo exemplo, temos que entrar na função pra destrinchar o retorno. Além de que fetchAll e fetchById são nomes bem genéricos. Já vi erro em API onde a pessoa estava quebrando a cabeça, e no final, o que estava acontecendo é que a pessoa fez duas funções com o nome igual no service de duas rotas diferentes. Na hora de importar para o controller, como os nomes eram iguais, acabou importando o service errado e aí o resultado você já sabe.

2

Acho válido o uso da nomeação usada no exemplo 2 quando a função ou variável já está dentro de um contexto que expecifica à qual entidade/recurso/substantivo se refere. Por exemplo, em uma classe UserRepository, ter métodos nomeados como findAllUsers ou findUserById é considerado uma má prática também, trazendo uma certa redundância no código. Então, a forma de nomear trazida no exemplo 2 se encaixa muito bem nesse contexto.
O ideal é você sempre especificar a qual contexto x variável ou função está relacionada

2

Concordo contigo, quando falamos de métodos de uma classe. Até porque isso ficaria bem legível, pois para chamar o método, obrigatoriamente a classe seria instanciada. Um exemplo é um controller chamando um service e pra isso você poderia fazer tipo:

const user = new userService();

E ai a partir disso você chama por exemplo o método fetchById:

const userData = await user.fetchByid(id);

E a outra forma seria pelos exports/imports numa abordagem mais funcional, ai faria mais sentido nomes mais descritivos.

1

Cara, sigo a mesma lógica que você para nomear. Acelera bastante o processo de encontrar um bom nome. obrigado pela contribuição. Sucesso!

2

Sensacional! Post extremamente necessário.
Na robótica, meus códigos são sempre um caos! A forma que eu consegui me organizar para melhorar um pouco nessa questão é a utilização de sufixos curtos, como "pos" para posição, "act" para atuador. Sigo esta linha mas sinto que ainda ha muito para melhorar.

Agradeço pela informação!

1

Siim! Esse é um tópico que normalmente negligenciamos. Só após nos depararmos com códigos maiores e de maior complexidade, nos damos conta o quão necessário é dar bons nomes. Fico feliz por ajudar e obrigado pelo comentário.

2

Por sorte percebi isso bem no comecinho, desde então sempre tomo cuidado máximo com a nomenclatura, não é atoa que passamos a maior parte do tempo com dificuldades em dar nomes ao invés do código hahaha, ótimo post dev :)

2
2

Sensacional esse post, tenho 8 meses como dev iniciante e tenho muita dificuldade em nomear minhas classes, métodos e meus atributos. fico realmente feliz com essa explicação, pois me traz uma reflexão e senso de melhoria. Obrigado!

2
1

Isso! Um exemplo é, ao juntar inglês e português, quando você criar uma váriavel

const data = ''

Não dá para identificar essa varivel guardará uma data (em português) ou dados (data em inglês)

2

Uma vez tive uma story para desenvolver na empresa em que trabalhava, que consistia em criar um campo para armazenar o número de protocolo de um sistema chamado "Conexão" em um sistema codificado em inglês.

Neste caso, o nome do campo e consequentemente da variável ficou "conexaoProtocolNo". Até cogitamos de colocar "connectionProtocolNo". Acabamos por seguir com a primeira opção pois "Conexão" é um nome próprio e portanto não deve ser traduzidos. De repente se passarem pela mesma situação, pode surgir o mesmo questionamento :)

2

belo resumo do capitulo do livro, vai ajudar bastante. Quem não leu ainda o Clean Code, tem muita coisa importante nesse livro, aaaaaaaaah como me ajudou nos meus rabisco que eu chamo de código

2

Curti demais essas dicas. Já entrou pra lista dos tópicos favoritos aqui pra dar aquela espiada quando a criatividade falhar! Obrigado pela ajuda, irmão! Sucesso!

2
2

vi um meme que se chama "pare de usar 'I' para LOOPS"
realmente temos diversas outras formas, chamar de I ao inves de INDEX reduz 400 milisegundos na digitação... mas acredito que nomear bem as variáveis é o caminho (clean code que o diga)

1

Sim! como levamos mais tempo lendo o código, é melhor perder esse tempo a mais na digitação e pensando em um nome melhor para a variável, que perder tentando entender, pois sempre vai ser um tempo bem maior na leitura. sucesso!

1

Eu, amigos e colegas passamos algumas dificuldades em nomear, vou compartilhar com eles Postagem massa, essas dicas ja estão nos meus favoritos.

1
1
1
1
1

Também relacionado a este assunto, podemos falar sobre convenções para nome de variáveis/funções que podem variar por linguagem de programação.

Snake case

É um estilo bastante comum na linguagem Python. Consiste em escrever tudo em lowercase, separando cada palavra por um underline. Exemplo: minha_primeira_variavel

(Lower) Camel case

Muito comum em linguagens como Java e JavaScript. Consiste em escrever a primeira palavra começando por uma letra minúscula e as palavras seguintes começando por letra maiúscula, sem espaços. Exemplo: minhaPrimeiraVariavel. Para classes, é comum usar o Upper Camel Case. Neste caso, a primeira palavra também se inicia com uma letra maiúscula.

Lembrando que isso não é uma obrigatoriedade, mas sim uma boa prática reconhecida pelas pessoas que trabalham com cada uma dessas linguagens.

1

Isso mesmo, boas práticas que ajudam no dia-a-dia pra que qualquer pessoa consiga ler e entender o código, indenpendente de quem escreveu.

Algumas linguagens/frameworks inclusive oferecem os Linters, que ajudam nessa questão de boas práticas.
Trazendo como exemplo o Flutter (com a linguagem Dart), ele possui o flutter_lints, que além de vir com regras de boas práticas de implementação, permite você incluir mais regras utilizando o arquivo analysis_options.yaml.

1
1
1