9 Diretrizes para Criar Nomes Expressivos

Nomear é subjetivo e situacional, é uma arte, e com a maioria das artes, descobrimos padrões. Aprendi muito através da leitura do código de outros. 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 deveria saber, baseado nos nomes, as responsabilidades da classe. Sim, eu sei que nomear é apenas um raio 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 na nomenclatura porque sinto que é 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, mudarmos o nome para DisplayNameFormatter temos 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, no 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 no 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 no 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 apenas com 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 detalhes, melhor — expresse a responsabilidade no nome.

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

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

Não Dependa de Comentários para 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 desodorante. É 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 “In 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ê encontrará outros locais onde é possível aproveitar o novo método, lugares que você nunca antecipou usar o novo método.

Às vezes quando chamamos um método o consumidor precisa saber algo particular sobre o método, se essa particularidade é 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, use outras maneiras de expressar intenção incluindo usar estrutura física e lógica e nomes para transmitir intenção.

Abstenha-se de 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 mais difícil para um novo engenheiro entender a intenção.

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ócio

Use a mesma terminologia no código como no domínio de negócio. Isso permite que engenheiros e especialistas no assunto (SME) comuniquem facilmente ideias porque compartilham o mesmo vocabulário. Quando não há um vocabulário compartilhado, traduções acontecem, 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 Jargão 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 veem algo nomeado “factory,” imediatamente pensam 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 engenheiros comunicarem ideias entre si.

A pior nomenclatura possível é cooptar terminologia da 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; // isso é confuso

if(!IsNotDeleted) { // fica ainda mais confuso quando o valor é negado
  //Do magic
}

Sem nome de variável negado:

var IsDeleted = true; // isso é confuso

if(!IsDeleted) { 
  //Do magic
}

Conclusão

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