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.