9 Diretrizes para Criar Nomes Expressivos

Nomenclatura é subjetiva e situacional, é uma arte, e como na maioria das artes, descobrimos padrões. Aprendi muito lendo o código de outras pessoas. Neste artigo, compilei 9 diretrizes que gostaria que outros tivessem seguido quando li seu código.

Quando um engenheiro de software abre uma classe, ele deve saber, baseado nos nomes, as responsabilidades da classe. Sim, eu sei que nomenclatura é apenas um aspecto da roda, estruturas físicas e lógicas também desempenham um papel significativo na compreensão do código, assim como a complexidade. Neste artigo, estou focando apenas em nomenclatura porque sinto que tem o impacto mais significativo na compreensão do código.

Não Inclua Tipo a Menos que Esclareça a Intenção

Um tipo pode ser qualquer coisa, desde um tipo de programação (string, int, decimal) até um agrupamento de responsabilidades (Util, Helper, Validator, Event, etc.). Frequentemente é uma classificação que não expressa intenção.

Vamos ver um exemplo: O nome StringHelper não expressa muito. Uma string é um tipo de sistema, e Helper é vago, StringHelper fala mais sobre o “como” do que sobre a intenção. Se em vez disso, mudássemos o nome para DisplayNameFormatter, teríamos uma imagem mais clara da intenção. DisplayName é muito específico, e Formatter expressa resultado. Formatter pode ou não ser um tipo, mas não importa, porque expressa intenção.

Sempre há exceções; por exemplo, em ASP.Net MVC, controladores devem terminar em “Controller” ou a aplicação não funciona. Usando paradigmas como Domain Driven Design (DDD), nomes como “Services,” “Repository,” “ValueType” e “Model” têm significado em DDD e expressam responsabilidade.

Por exemplo, UserRepository implica que dados de usuário são recuperados e salvos em um armazenamento de dados.

Evite Metáforas

Metáforas são culturais, e engenheiros de outras culturas podem não entender a intenção.

Metáforas comuns nos Estados Unidos:

• Beating a dead horse
• Chicken or the egg
• Elephant in the room

Metáforas comuns na Nova Zelândia:

• Spit the dummy
• Knackered
• Hard yakka

Use Verbos

Steve Yegge escreveu um (muito longo) post de blog sobre usar verbos em vez de substantivos.

Seu ponto é usar verbos, aplicações são compostas de substantivos, mas substantivos não fazem coisas. Sistemas são inúteis com apenas substantivos, em vez disso, expresse ação nos nomes dos métodos.

Por exemplo, UserAuthentication*(substantivo).AuthenticateUser(ação/verbo)* expressa a ação de verificar as credenciais de um usuário.

Seja Descritivo

Seja descritivo, quanto mais detalhe, melhor — expresse a responsabilidade no nome.

Pergunte-se, qual é a única coisa que esta classe ou função faz bem?

Se você tiver dificuldade em encontrar um nome, a classe ou função pode ter mais de uma responsabilidade e, portanto, estar violando o Princípio da Responsabilidade Única.

Não Dependa de Comentários para Expressar Intenção

Comentários são uma ótima maneira de fornecer contexto adicional ao código, mas não dependa de comentários. Os nomes de classes e métodos devem se sustentar por si só.

Em Refactoring: Improving the Design of Existing Code por Martin Fowler, Kent Beck, John Brant, William Opdyke, e Don Roberts:

… comentários são frequentemente usados como desodorizante. É surpreendente com que frequência você olha para código densamente comentado e percebe que os comentários estão lá porque o código é ruim.

Outra citação maravilhosa dos autores de “Refactoring”:

Quando você sente a necessidade de escrever um comentário, primeiro tente refatorar o código para que qualquer comentário se torne supérfluo. Página 88

Muitas vezes, quando o código é refatorado e encapsulado em um método, você descobrirá outros locais onde é possível aproveitar o novo método, lugares que você nunca antecipou usar o novo método.

Às vezes, ao chamar um método, o consumidor precisa saber algo particular sobre o método, se essa particularidade faz parte do nome, então o consumidor não precisa revisar o código-fonte.

Aqui está um exemplo de incorporar um comentário em um nome.

Com comentários:

// without tracking
var user = GetUserByUserId(userId);

Refatorado para incluir o comentário no nome do método:

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

Outros engenheiros agora sabem que este método não tem rastreamento antes de precisarem ler o código-fonte ou encontrar o comentário.

Comentários devem ser sua última linha de defesa quando possível, prefira outras maneiras de expressar intenção, incluindo usar estrutura física e lógica e nomes para transmitir intenção.

Evite Usar Nomes com Significado Ambíguo

Evite nomes com significados ambíguos. O significado de nomes ambíguos muda de projeto para projeto, o que torna a compreensão da intenção mais difícil para um novo engenheiro.

Aqui está uma lista de nomes ambíguos comuns:

• Helper
• Input
• Item
• Logic
• Manager
• Minder
• Moniker
• Nanny
• Overseer
• Processor
• Shepherd
• Supervisor
• Thingy
• Utility
• Widget

Use a Mesma Linguagem do Domínio de Negócios

Use a mesma terminologia no código que no domínio de negócios. Isso permite que engenheiros e especialistas no assunto (SME) se comuniquem facilmente porque compartilham o mesmo vocabulário. Quando não há um vocabulário compartilhado, a tradução acontece, o que invariavelmente leva a mal-entendidos.

Em um projeto em que trabalhei, o negócio começou com “Pupil” e depois mudou para “Student.” Os engenheiros de software nunca atualizaram o software para refletir a mudança na terminologia. Quando novos engenheiros se juntaram ao projeto, a maioria acreditava que Pupil e Student eram conceitos diferentes.

Use Terminologia da Indústria

Quando possível, use terminologia que tenha significado em toda a indústria de software.

A maioria dos engenheiros de software, quando vê algo nomeado “factory,” imediatamente pensa no padrão factory.

Usar paradigmas de aplicação existentes, como “Clean Architecture” e “Domain Driven Design,” facilita o compartilhamento de ideias e cria uma linguagem comum para os engenheiros se comunicarem entre si.

A pior nomenclatura possível é cooptar terminologia amplamente usada na indústria e dar a ela um significado diferente.

Ao Nomear Booleanos…

Nomes booleanos devem sempre ser uma resposta a uma pergunta com seu valor sendo verdadeiro ou falso.

Por exemplo, isUserAuthenticated, a resposta é sim (true) ou não (false)

Use palavras como:

• Has
• Does
• Is
• Can

Evite nomes negados, por exemplo:

Um nome de variável negado:

var IsNotDeleted = true; // this is confusing

if(!IsNotDeleted) { // it gets even more confusing when the value is negated
  //Do magic
}

Sem nome de variável negado:

var IsDeleted = true; // this is confusing

if(!IsDeleted) { 
  //Do magic
}

Conclusão

Escolher nomes expressivos é crucial para comunicar intenção, design e conhecimento de domínio ao próximo engenheiro. Frequentemente trabalhamos em código para corrigir defeitos ou incorporar novos recursos, e estamos continuamente compilando código em nossa mente tentando entender como funciona. Nomenclatura nos dá dicas sobre o que o engenheiro anterior estava pensando, sem essa comunicação entre engenheiros do passado e do futuro, nos prejudicamos no crescimento da aplicação. Potencialmente condenando o projeto ao fracasso.