Por que se preocupar com nomes no seu código?

Quando você está desenvolvendo, preocupa-se com os nomes das classes, propriedades, métodos e varáveis fiquem claras mostrando o real objetivo daquele código? Pensar em nomes parece uma tarefa simples e que não vai afetar a produtividade da equipe, mas existem boas práticas a se seguir na escolha de nomes. Vamos entender um pouco mais sobre esse assunto!

Nomes objetivos são importantes

Ter nomes que não refletem bem o objetivo do seu código pode dificultar e direcionar outros desenvolvedores a irem para o caminho errado ao analisar seu código ou perderem tempo. Veja o exemplo abaixo:

public void PreencherDados();
public void ComecarProcesso();

// Em inglês

public void FillData();
public void StartProcessing();

Você acredita que esses métodos tem nomes claros? Analise bem. O primeiro método PreencherDados() tem um nome muito obscuro. Estamos preenchendo que tipo de dados? São dados referente a uma conta, cliente... não está claro. O desenvolvedor que está realizando uma manutenção no código ou implementando uma funcionalidade nova precisa assim ler o código todo para entender o que aquele método realmente faz, então ele descobre que o método preenche as informações do cliente.

E o que podemos concluir sobre o método ComecarProcesso();? Que tipo de processo está sendo iniciado? Uma rotina, tarefa especifica, gerar arquivos ou verificações? Não sabemos ao certo e para ter uma visão clara do que o método faz é preciso ler o código e talvez seja preciso depurar. Depois de ler o método o programador descobre que o objetivo é começar o processo para gerar arquivos XML.

Como podemos melhorar esses métodos? Escolhendo nomes significativos que vão dar sentido e direção sobre o que eles realmente fazem:

public void PreencherInformacaoCliente();
public void GerarArquivoXml();

// Em inglês

public void FillCustomerInformation ();
public void GenerateXmlFile();

Pode não ser no momento os melhores nomes. Mas com certeza deixa mais claro o real propósito do método!

Evite nomes com abreviações desconhecidas

Nomes abreviados podem fazer todo o sentido para você, mas para outro desenvolvedor não! Veja este exemplo clássico que Robert Cecil Martin apresentou em uma das suas obras sobre código limpo:

class DtaRcrd102 {
private Date genymdhms;
private Date modymdhms;
};

Pelo que essa propriedade é responsável? Baseando-se pelo tipo Date, podemos tentar adivinhar, mas provavelmente não vai ficar claro o objetivo dela até analisarmos todo o fluxo de código. O nome da classe também não ajuda muito, agora veja uma nomenclatura mais adequada que ele apresentou no livro:

class Customer {
private Date generationTimestamp;
private Date modificationTimestamp;
};

Agora sim fica muito claro. Trata se de uma marcação de horário e a segunda se refere a modificação do horário. Vemos claramente a importância de bons nomes e sem abreviações! Isso facilita também a comunicação com a equipe, como o próprio Uncle Bob disse:

"Agora sim é possível ter uma conversa mais inteligente."

Veja outros exemplos de abreviações que devemos evitar e farei um breve comentário sobre uma experiência que passei com as duas ultimas:

string IniMess;
string DocsGrp;

string AddrTo;
Date dtUp;

int AnyProblem;
bool SoldOff;

Me deparei em um projeto com essas propriedades e não fazia a menor ideia do proposito delas para aplicação. Afinal o que seria AnyProblem (Algum Problema)? Ou SoldOff (esgotado)? Analisei o contexto e as classes na esperança de que isso respondesse minhas dúvidas. Quando analisei a classe, surgiram mais dúvidas ainda, e me perguntava o que poderia estar esgotado? O tempo, um voucher, os ingressos? E pior ainda era anyProblem. Algum problema do que? De comunicação, conexão? Eu não fazia a menor ideia. Tive que consultar meus colegas de trabalho. Nem eles sabiam! Apenas o responsável pela arquitetura sabia a resposta. Mas para a equipe e novos integrantes não fazia nenhum sentido.

Veja essas propriedades com nomes melhores:

string InitializationMessage;
string DocumentGroup;
string Addressee;
Date DateUpdate;

Existem casos que abreviações são comuns, como PDF, URL, JSON entre outras. Quando uma abreviação é conhecida globalmente e não surgiu da sua cabeça ela é bem vinda a ser usada. Mas mesmo assim tome cuidado e deixe o nome mais claro possível.

Use verbos para nomear seus métodos.

O que são métodos? Ações, comportamentos. Por isso é muito bom usar verbos. Veja as duas opções a abaixo:

// Opção 1

GerarContratoEmprestimo();

// Opção 2

GerandoContratoEmprestimo();

A primeira opção se encaixa bem para um nome de método.

Evite nomes semelhantes

Imagine que você acabou de entrar em um projeto onde a aplicação tem o objetivo de gerar vários tipos de relatórios, os nomes dos métodos estão assim:

double GerarTotalDsMensal();
double GerarTotalCsMensal();
double GerarTotalRcMensal();

Os nomes estão muito semelhantes e o desenvolvedor que não prestar atenção pode confundir os métodos caso precise alterar ou criar novas funcionalidades no código. Lembre-se que para você pode fazer sentido esse nome, para outros isso não faz!

Podemos corrigir isso de outras maneiras, mas como o foco do artigo é nomenclaturas vou focar na solução mais simples agora:

double TotalDespesaMensal();
double TotalCustoMensal();
double TotalReceitaMensal();

Convenções de Nomenclatura

Vamos abordar apenas dois pontos da convenção que são CamelCase e PascalCase, veja exemplos dos dois:

// CamelCase

valorMensal , nomeCompleto, precoProduto

// PascalCase

CalcularPrecoVarejo(), EnviarEmailDiretoria()

É sempre importante buscar adotar um padrão no seu projeto. Isso vai ajudar a deixar o código bem organizado. Você pode escolher qual adotar, segue uma dica:

• Usar CamelCase para variáveis e parâmetros de métodos.
• Nomear classes e métodos usando PascalCase.

Outra dica é evitar usar a notação húngara. Caso queira entender do que se trata veja essa tabela:

Com base na tabela você já entende que se nomear variáveis dessa forma você terá dificuldades de leitura no futuro e a medida que o projeto cresce. Vou até citar o que Robert C. Martin disse em sua obra Clean Code :

" Hoje em dia, a NH (notação húngara) e outras formas de convenção de tipos são basicamente obstáculos! "

Conclusão

Desenvolver Software é uma tarefa que exige muita atenção até para nomenclaturas. Portanto tenha em mente que quando está desenvolvendo, outro programador pode no futuro ter que alterar ou realizar uma manutenção em seu código, você pode ou não ajudar muito caso tenha se preocupado em nomear suas variáveis e métodos da maneira mais clara e objetiva.

Fico por aqui nesse post, até o próximo 😁!