Há apenas duas coisas difíceis na Ciência da Computação: invalidação de cache
e nomear coisas.
- Phil Karlton
Nós, desenvolvedores, gastamos mais tempo lendo código do que escrevendo. É importante que o código seja legível e claro sobre sua intenção.
Abaixo estão alguns conselhos baseados na minha experiência em nomear coisas.
Significado
Um nome, seja uma variável, uma propriedade, uma classe ou uma interface, deve refletir o propósito de por que está sendo apresentado e como é usado.
Use nomes precisos
Se não se pode ter uma idéia sobre o uso e a finalidade sem comentários adicionais, o nome não é bom o suficiente. Se o uso imediato ou a ideia de finalidade com base na nomeação estiverem incorretos, a nomeação será inaceitável.
A pior nomeação possível é quando um nome de método está para quem o lê.
Evite nomes sem sentido
São nomes como $i , $j , $k etc. Embora estes sejam bons para uso em ciclos, em outros casos eles estão desperdiçando legibilidade.
Uma fonte comum desses nomes é a ciência clássica, na qual a maioria das fórmulas usa variáveis de uma letra, tornando mais rápida a escrita. Como conseqüência, você não pode entender essas fórmulas sem um parágrafo introdutório que explique a nomenclatura. Muitas vezes, este parágrafo é difícil de encontrar.
Como o ensino da ciência da computação inclui um número significativo de disciplinas clássicas da ciência, os estudantes estão se acostumando a esse nome e o trazem para a programação.
Nomeando classes, interfaces, propriedades e métodos
O nome da classe deve ser um ou vários substantivos. Não deve haver verbos. Tente evitar "dados", "gerente", "informações", "processador", "manipulador", "fabricante", "util" etc. como estes geralmente um indicador de nomeação vaga.
As interfaces são geralmente substantivos ou adjetivos. Algumas equipes, incluindo PHP-FIG , optaram por fixar interfaces com a Interface . Alguns fazem isso com o prefixo I e outros não usam prefixo ou postfix. Acho tudo isso aceitável caso você seja consistente.
As propriedades devem ser nomeadas com substantivos ou adjetivos. Para booleanos, use frases afirmativas com o prefixo "Is", "Can" ou "Has", quando apropriado.
Os nomes dos métodos devem conter um ou mais verbos, pois são ações. Escolha o verbo que descreve o que o método faz, não como ele faz.
Embora não seja estritamente necessário, é uma boa idéia finalizar o nome da classe derivada com o nome da classe base:
class Exception {} class InvalidArgumentException extends Exception {}
Consistência
Use um único nome para um único conceito. Seja consistente.
Um bom exemplo é usar o begin / end qualquer lugar, em vez de misturá-lo com o start / finish .
Siga as convenções de estilo de código
Ao desenvolver um projeto, uma equipe deve concordar com o estilo do código e as convenções de nomenclatura que eles usam e as seguem. Se uma parte das convenções não for aceita por alguns membros da equipe, ela deverá ser revisada, alterada e nova regra deve ser definida.
Para PHP, a convenção mais comum atualmente é o PSR-2 e a maioria das convenções internas do projeto são baseadas nela.
Verbosidade
Evite reutilizar nomes
O uso do mesmo nome para muitos conceitos deve ser evitado, se possível, pois traz dois problemas:
- Ao ler, você deve manter o contexto em mente. Geralmente, isso significa chegar ao namespace ou à declaração do pacote constantemente.
- Procurar por esses nomes é uma dor.
Evite contrações
Não use contrações. Exemplos comuns são:
function cntBigWrds($data, $length) { $i = 0; foreach ($data as $iter) { if (mb_strlen($iter) > $length) { $i++; } } return $i; } $data = ['I', 'am', 'word']; echo cntBigWrds($data, 3);
O código acima, quando nomeado corretamente, se torna:
function countWordsLongerThan(array $words, int $minimumLength) { $count = 0; foreach ($words as $word) { if (mb_strlen($word) > $minimumLength) { $count++; } } return $count; } $words = ['I', 'am', 'word']; echo countWordsLongerThan($words, 3);
Observe ainda que nomes explicativos curtos sem contrações são melhores que nomes explicativos longos, portanto, não exagere na verbosidade ao extremo, terminando com nomes como processTextReplacingMoreThanASingleSpaceWithASingleSpace() .
Se o nome for muito longo, significa que pode ser reformulado para torná-lo mais curto ou a coisa que você está nomeando está fazendo muito e deve ser refatorada em várias coisas.
Evite acrônimos
Evite siglas e abreviações, exceto as conhecidas como HTML. Elon Musk enviou um e-mail intitulado "Acrônimos seriamente sugados" para todos os funcionários da SpaceX em maio de 2010:
Há uma tendência crescente a usar acrônimos inventados na SpaceX. O uso excessivo de siglas inventadas é um impedimento significativo à comunicação e manter a comunicação boa à medida que crescemos é incrivelmente importante. Individualmente, algumas siglas aqui e ali podem não parecer tão ruins, mas se milhares de pessoas as inventarem, com o tempo, o resultado será um glossário enorme que devemos emitir para os novos funcionários. Ninguém consegue se lembrar de todos esses acrônimos e as pessoas não querem parecer idiotas em uma reunião, então apenas ficam ali, ignorantes. Isso é particularmente difícil para os novos funcionários.
Isso precisa parar imediatamente ou tomarei medidas drásticas - dei um aviso suficiente ao longo dos anos. A menos que um acrônimo seja aprovado por mim, ele não deve entrar no glossário da SpaceX. Se houver um acrônimo existente que não possa ser razoavelmente justificado, ele deverá ser eliminado, como solicitei no passado.
Por exemplo, não deve haver designações "HTS" [suporte de teste horizontal] ou "VTS" [suporte de teste vertical] para bancadas de teste. Esses são particularmente burros, pois contêm palavras desnecessárias. Um "suporte" em nosso local de teste é obviamente um suporte de teste. VTS-3 é quatro sílabas em comparação com "Tripod", que é dois, então a versão sangrenta da sigla leva mais tempo para dizer do que o nome!
O teste principal para um acrônimo é perguntar se isso ajuda ou prejudica a comunicação. Um acrônimo que a maioria dos engenheiros fora da SpaceX já conhece, como GUI, é bom de usar. Também é bom inventar algumas siglas / contrações de vez em quando, supondo que eu as tenha aprovado, por exemplo, MVac e M9 em vez de Merlin 1C-Vacuum ou Merlin 1C-Sea Level, mas essas devem ser reduzidas ao mínimo.
Eu concordo com ele.
Legibilidade
O código deve ser capaz de ser lido tão facilmente quanto a prosa. Escolha as palavras que você escolheria para escrever um artigo ou um livro. Por exemplo, uma propriedade chamada TotalAmount é mais legível em inglês que AmountTotal .
Ocultando detalhes da implementação
Isso é mais sobre design orientado a objetos, mas afeta muito a legibilidade se os detalhes da implementação forem expostos. Tente não expor métodos nomeados como:
initializeinitcreatebuild
Idioma do domínio
O código deve usar os mesmos nomes usados no modelo comercial ou de domínio automatizado.
Por exemplo, se uma empresa de viagens que usa "local" como um nome geral para cafés, hotéis e atrações turísticas, é uma má idéia usar "local" no código porque você e seus usuários falam dois idiomas diferentes, tornando-o mais complicado do que deveria.
Essa linguagem é freqüentemente chamada de "A linguagem onipresente". Você pode aprender mais no mini-livro " Domínio Orientado ao Design Rapidamente " da InfoQ.
Inglês
A maioria das linguagens de programação usa o inglês para construções internas e também é uma boa prática nomear coisas em inglês. É extremamente importante para um desenvolvedor aprender inglês pelo menos no nível básico e, o que é mais importante, ter um bom vocabulário que se possa usar para encontrar um bom nome.
Algumas ferramentas úteis:
Referências