Aqui está a tradução do artigo do blog Better Programming no site Medium. Nele, o programador Daan compartilha regras simples, seguindo as quais você pode atribuir bons nomes a funções e variáveis.
Como desenvolvedor, você provavelmente gasta muito tempo criando variáveis e criando seus nomes. Os nomes estão em toda parte: são necessários para arquivos, classes, métodos e essas mesmas variáveis.
Como passamos muito tempo atribuindo nomes, é muito importante fazer isso de uma maneira de qualidade. Neste artigo, falarei sobre algumas regras simples, após as quais você pode criar bons nomes. Afinal, isso é uma arte inteira!
Use nomes que revelem suas intenções
O nome deve indicar a finalidade do código. Mais fácil falar do que fazer, certo? Com que frequência você encontra variáveis com nomes que não dizem nada sobre a intenção do programador?
A regra é a seguinte: se um nome requer comentário, não transmite intenção.Há uma variável nesse trecho de código cujo nome não é claro:
<?php private $s;
A variável
$s não nos diz nada e não está associada a um período de tempo. É melhor escolher um nome que indique o que e em que unidades é medida.
Um dos nomes abaixo seria mais apropriado.
<?php private $days_since_creation; private $elapsed_time_in_seconds; private $seconds_since_last_modified;
Os nomes de intenção tornam o código mais fácil de entender e, portanto, mais fácil de manter.
Você gastará tempo escolhendo o nome certo, mas salve-o no futuro.
Considere este exemplo:
<?php function getList() { $list1 = []; foreach ($this->the_list as $x) { if ($x % 2 != 0) { $list1[] = $x; } } return $list1; } function getOddNumbers() { $odd_numbers = []; foreach ($this->numbers as $number) { if (isOdd($number)) { $odd_numbers[] = $number; } } return $odd_numbers; }
Por que é difícil entender o que a função
getList ? Sem expressões complexas, o código está alinhado e formatado corretamente, apenas três variáveis e nada mais.
Agora observe a função
getOddNumbers . Você viu que ela faz a mesma coisa que
getList ?
Observe que o código não se tornou mais complicado ou mais simples. Mantivemos o número de operadores, variáveis e níveis de aninhamento, mas agora é mais claro e transparente.
Uma pequena mudança no nome - e já é muito mais fácil entender o que está acontecendo.
Evite desinformação
Tente evitar associações falsas que distorcem o objetivo do código.
Não use palavras que possam ser entendidas de maneira diferente da pretendida. Por exemplo, não
productList grupo de produtos
productList , a menos que seja realmente um objeto do tipo
List . Esse nome pode levar a conclusões falsas. É melhor usar apenas
products .
Talvez os piores nomes para variáveis comecem com uma letra maiúscula
O e uma letra minúscula
L , pois esses caracteres são muito semelhantes a 0 e 1.
Também tenha cuidado com nomes que são apenas ligeiramente diferentes um do outro. Quanto tempo passará até você notar uma pequena diferença entre
SomeMethodForEfficientHandlingOfFiles em um arquivo e
SomeMethodForEfficientStorageOfFiles em outro? Concordo, à primeira vista eles são idênticos.
Destacar diferenças significativas
Usar numeração não é a melhor maneira de nomear. Esses nomes não são informativos, pois não revelam as intenções do autor.
Vejamos o seguinte exemplo:
<?php public function duplicateArray($arr1, &$arr2) { foreach ($arr1 as $key => $value) { $arr2[$key] = $value; } }
Esse trecho de código será melhor se renomearmos
$arr1 e
$arr2 para
$source e
$destination .
Use nomes que você possa pronunciar
Se você não pode pronunciar o nome da função, é improvável que você possa falar sobre isso e não pareça idiota. Isso é realmente importante porque discutir o código faz parte da programação. No entanto, cada um de nós deve ter encontrado variáveis com nomes impronunciáveis.
Suponha que você tenha uma variável chamada
$xsq e frequentemente a discuta com a empresa. E aqui você está conversando com um colega:
- Bem, o que há com ex es quew?
- com o que? Com fila de acesso?
Alguns dos desenvolvedores pronunciarão o nome da variável como uma palavra e outros como uma abreviação.
Use nomes pesquisáveis
O problema com nomes de uma letra é que eles são difíceis de encontrar no código.
A mesma coisa com constantes numéricas. É melhor substituí-los por variáveis. Por exemplo, o número usual 8 pode causar muitos problemas se você precisar encontrar algo no código. No entanto, será muito mais fácil se você substituir o número por algo como
MAX_BLOCKS_DISPLAYED .
A única situação em que vale a pena usar nomes de uma única letra é inventar nomes para variáveis locais dentro de métodos curtos.
Prefixos de Membro da Classe
Não use m_ prefixos.
Alguns desenvolvedores costumam usar um prefixo de sublinhado na frente dos membros da classe. Não faça isso. Suas classes e métodos devem ser compactos o suficiente para que você não precise de nenhum desses prefixos.
Como alternativa, você pode usar o IDE (ou instalar o plug-in), que destaca as variáveis dependendo do seu escopo.
Pense no seu código como um local para piquenique na floresta - deixe-o mais limpo do que era antes de chegar.
Conclusão
É assim que nomes mais compreensíveis para o código são criados.
Comente, deixe suas perguntas e escreva se quiser que eu cubra outros tópicos relacionados à programação.
Este artigo foi inspirado no livro de Robert Martin, Clean Code, que eu recomendo a leitura.