Deblogger

Nomes com Significados

Os nomes estão por toda parte nos nossos softwares. Nomeamos nossas variáveis, nossas funções, argumentos, classes e pacotes. Nomeamos nossos arquivos de origem e os diretórios que os contêm. Porque fazemos muito isso, é melhor fazermos bem. O que se segue são algumas regras simples para criar bons nomes, sugeridas por Robert C. Martin no livro Clean Code.

Use nomes que revelem intenção

Seja o mais descritivo possível nos nomes das variáveis. Evite usar apenas um caractere ou abreviações. Dessa forma evitamos que outros desenvolvedores que forem dar manutenção ao código fiquem perdidos ou gastem tempo decifrando o que aquela variável representa para o código. O nome de uma variável ou constante deve descrever o que ela representa naquele contexto.

Veja o código a seguir:

export function shuffle(a) {
  for (let i = a.length - 1; i > 0; i -= 1) {
    const n = Math.floor(Math.random() * (i + 1));
    [a[i], a[n]] = [a[n], a[i]];
  }
  return a;
}

O nome a não representa e não revela nada, tampouco os nomes i ou n. Embora seja uma convenção utilizar do i como a representação de um índice numa iteração de laços for, ela não tem valor semântico nenhum. Parafraseando Uncle Bob:

O nome de uma variável, função ou classe deve responder a todas as grandes questões. Ele deve dizer por que existe, o que faz e como é usado. Se um nome requer um comentário, o nome não revela sua intenção.

Robert C. Martin

Sendo assim, vamos tentar melhorar um pouco a semântica do código, para deixá-lo mais legível:

export function shuffleArray(array) {
  for (let index = array.length - 1; index > 0; index -= 1) {
    const newIndex = Math.floor(Math.random() * (index + 1));
    [array[index], array[newIndex]] = [array[newIndex], array[index]];
  }
  return array;
}

Com a mudança nos nomes, logo de cara conseguimos entender o que cada variável representa dentro do escopo da função, além da mudança na nomenclatura da função deixar mais explícito o que ela faz.

Evite desinformação

Devemos evitar deixar pistas falsas que ocultam o significado do código. Devemos evitar palavras cujos significados estabelecidos variam de acordo com o significado pretendido. Por exemplo, não use accountList como nome de uma variável se o tipo primitivo desta não for uma lista. Também não use nomes que variam em pequena escala. Por exemplo, quanto tempo você demora para detectar a diferença entre XYZControllerForEfficientHandlingOfStrings e XYZControllerForEfficientStorageOfStrings? Além dessa demora na diferenciação, se você usar uma IDE com pesquisa e preenchimento automático, esta regra melhora a maneira como você pesquisa e escreve o seu código.

Faça distinções significativas

Nós criamos problemas para nós mesmos quando escrevemos código unicamente para satisfazer um compilador ou interpretador. Como não podemos usar o mesmo nome para duas coisas diferentes no mesmo escopo, podemos tender a fazer uma mudança aleatória em um dos nomes. Às vezes isso é feito escrevendo um erro ortográfico em um deles, o que pode ocasionar num erro de compilação se futuramente alguém topar nesse erro e corrigi-lo. Também não faz sentido adicionar letras ou números no final dos nomes, como array1 e array2. Se os nomes precisam ser diferentes, os significados também precisam.

Use nomes pronunciáveis

Escrever código é uma atividade em grupo. Sendo assim, raramente você trabalhará em uma empresa onde é o único desenvolvedor, e não precisará conversar sobre o seu código com ninguém. Código impronunciável é código indiscutível. Se você precisar conversar com alguém sobre a variável genymdhms, você provavelmente vai soar muito estranho se soletrá-la ou tentar emitir um som que se assemelhe à escrita. Se o nome desta fosse generationTimestamp, ficaria mais fácil citá-la em um conversa.

Use nomes pesquisáveis

Se uma variável ou constante puder ser usada em vários lugares do código, é importante dar a ela um nome amigável para pesquisa. Compare, pro exemplo, os os dois blocos de código a seguir:

for (let j = 0; j < 34; j++) {
    s += (t[j] * 4) / 5;
}
const workDaysPerWeek = 5;
const numberOfTasks = 34;
const realDaysPerIdealDay = 4;
let sum = 0;
for (let index = 0; index < numberOfTasks; index+= 1) {
    const realTaskDays = taskEstimate[index] * realDaysPerIdealDay;
    const realTaskWeeks = (realTaskDays / workDaysPerWeek);
    sum += realTaskWeeks;
}

A variável sum não é realmente útil por uma visão semântica, mas pelo menos é pesquisável. O código intencionalmente nomeado torna a função mais longa, mas verifique como será mais fácil encontrar workDaysPerWeek do que encontrar todos os lugares onde 5 foi usado.

Nomes de Classes e Objetos

Classes e objetos devem ter nomes ou frases nominais como client, wikiPage e account. Evite palavras como manager, processor, data, ou info no nome de uma classe. O nome de uma classe não deve ser um verbo.

Nomes de Métodos

Os métodos devem ter nomes com verbos ou frases verbais, como postPayment, deletePage ou save.

Escolha uma palavra por conceito

Ao começar a ter uma base de código realmente grande, você e seu time podem começar a falhar em ser consistentes nos conceitos. Isso pode acabar tendo um fetch, retrieve e get como métodos equivalentes de classes diferentes.

Imagine que você usa fetch para chamar uma API que preenche seu objeto e consegue retornar apenas o valor de alguma propriedade. E se você começar a confundir os dois? Você precisará sempre verificar qual é o comportamento desse método específico se você não seguir o conceito. Sendo assim escolha uma palavra para um conceito abstrato e continue com ela.

Conclusão

O mais difícil em escolher bons nomes é que isso requer boas habilidades descritivas e um background cultural compartilhado. Esta é uma questão de ensino e não uma questão técnica, comercial ou administrativa. Como resultado, muitas pessoas não aprendem a fazer isso muito bem.

As pessoas também têm medo de renomear as coisas por medo de que outros desenvolvedores se oponham. Contudo, esse medo se dissolve quando descobrimos que é extremamente válido quando os nomes mudam (para melhor). Na maioria das vezes, não memorizamos realmente os nomes das classes e métodos. Para lidar com esses detalhes, usamos ferramentas modernas para lidar, assim nos concentramos em saber se o código pode ser lido como parágrafos e sentenças, ou pelo menos como tabelas e estrutura de dados (uma frase nem sempre é a melhor maneira de exibir dados). Provavelmente, você acabará surpreendendo alguém ao renomear, assim como faria com qualquer outra melhoria de código. Não deixe que isso o detenha.

Siga algumas dessas regras e veja se você não melhora a legibilidade do seu código. Se você estiver mantendo o código de outra pessoa, use ferramentas de refatoração para ajudar a resolver esses problemas. Vai valer a pena no curto prazo e continuará a valer no longo prazo.


Este é o primeiro artigo da série Clean Code.

Avalie:
5 (5)

Publicado por Mauro Oliveira

Desenvolvedor apaixonado por JavaScript, especialista em VueJS. Atualmente focado em padrões de projeto e código, estudando sobre testes unitários, Clean Code e segurança em aplicações Web, Mobile e Desktop.

Participe da discussão

1 comentário

Deixe um comentário

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