O capítulo 02 do livro "Código limpo" fala sobre nomeação.

Mas nomeação de que, exatamente? Bom, quando falamos em software, temos nomes em vários lugares: variáveis, funções, classes, parâmetros, módulos, arquivos-fonte, diretórios, etc.

Portanto, vamos falar sobre criar bons nomes:

1. Use nomes que revelem o seu propósito

O nome de uma variável, função, classe, etc, deve dizer o porquê aquilo existe, o que ele faz e como é utilizado. Se um nome requer um comentário, então ele não revela seu propósito.

Exemplo:

Int d; // tempo decorrido em dias

Isso não significa absolutamente nada. Nem mesmo o comentário está bom o bastante para entendermos. Tempo de quê estamos falando com esta variável?

Um exemplo, seria nomear como daysSinceFileCreation, que significaria o tempo de dias que se passaram desde que um arquivo foi criado, por exemplo. Muito melhor, não?

Mesmo um código simples pode não ter um propósito, ou pelo menos você não consegue identificar este propósito porque as variáveis não estão definidas de forma com que mostrem pra que servem, o que fazem, por que existem, etc.

Quando falo de variáveis, quero dizer qualquer coisa que pode ser nomeada.

O ponto é: escolha nomes que não fique difícil entender o que está acontecendo. Seja extremamente explícito e não importa se o nome ficar muito grande, precisa ser descritivo.

Uma diferença entre um programador esperto e um programador profissional é que este entende que clareza é fundamental. Os profissionais escrevem códigos que outros possam entender.

2. Evite informações erradas

Se você criar uma variável chamada de accountsList, mas se o que armazena as contas não for uma List de verdade, é uma informação errada e pode confundir.

Outro ponto: não utilize nomes muito parecidos, como ControllerForEfficientHandlingOfStrings e ControllerForEfficientStorageOfStrings. São muito semelhantes e passíveis de confusões.

3. Faça distinções significativas

Como você diferencia uma função chamada de getAccount para getAccountInfo? Muito difícil, não? E como você diferencia uma classe chamada de ProductData e ProductInfo? Imagine que você acabou de chegar no projeto. Como você deve saber qual utilizar? Complicado, certo?

Isso normalmente acontece pois não é possível usar o mesmo nome para referir-se a duas coisas diferentes num mesmo escopo, então há a alteração de forma meio "arbitrária", sem pensar. Não faça isso! Faça distinção dos nomes de uma forma que o leitor compreenda as diferenças.

4. Use nomes pronunciáveis

Imagine criar uma variável mdy para representar mês, dia e ano? Ou pior, uma variável chamada gdymdym que representa "generate date, year, month, day, hour, minute"? Como isso seria pronunciável? Impossível, certo? Além de que não é nem um pouco descritível.

5. Use nomes passíveis de busca

Imagine que você declare uma variável s que realiza a soma dos salários de membros de uma equipe. Quando você for buscar pela variável s, no seu código, irá se deparar com várias outras palavras que contém a letra s.

Você deve preferir nomes com uma única letra apenas se forem usados como variáveis locais dentro de métodos pequenos, como por exemplo i para referir ao index de um elemento de um array dentro de um loop.

O tamanho de um nome deve ser proporcional ao tamanho do escopo.

6. Nomes de classes

Classes e objetos devem ter nomes com substantivo(s), como Customer, Account, AddressParser, etc. Não deve ser um verbo e não deve ser genérico, como Parser, Data, Info, etc.

7. Nomes de métodos

Nomes de métodos devem possuir verbos indicando a ação realizada pelo método, como deletePage, savePage, getBalanceFromAccount, etc.

Use e abuse de prefixos, como get, para recuperar um valor, set para definir ou atualizar um valor, is para métodos que verificam uma condição, retornando um booleano, etc.

8. Utilize uma palavra por conceito

É essencial manter a clareza na nomenclatura. Considere, por exemplo, que em um projeto existem dois componentes distintos: um chamado UserController e outro nomeado como TransactionManager. Isso pode gerar confusão, especialmente para quem é novo na equipe.

Afinal de contas, qual a real diferença entre um 'Controller' e um 'Manager'? Ambos não desempenham funções semelhantes no projeto? Essa ambiguidade de nomes pode levar a mal-entendidos desnecessários. Alguém pode até pensar que 'Controller' e 'Manager' representam conceitos de programação distintos e perder tempo procurando explicações para essa suposta diferença.

Para evitar essa confusão, é necessário adotar uma abordagem consistente na escolha de nomes. Se um componente é denominado como 'Controller', então outros componentes com funções semelhantes devem seguir essa nomenclatura.

9. Adicione um contexto significativo

Quando você tem um conjunto de variáveis como firstName, lastName, street, number, city, state e zipcode, juntas elas claramente representam um endereço. No entanto, a situação muda quando você encontra uma dessas variáveis, como state, ou number, isoladamente em um método. Não é imediatamente óbvio que state faz parte de um endereço.

Uma forma de resolver isso é usar prefixos para dar contexto às variáveis. Por exemplo, addressFirstName, addressLastName e assim por diante. Esses prefixos ajudam a indicar que estas variáveis são partes de uma estrutura maior, no caso, um endereço.

Entretanto, uma abordagem mais eficaz seria criar uma classe chamada Address. Com essa classe, até o compilador reconheceria que estas variáveis pertencem a um contexto maior. Isso não só ajuda na organização do código, mas também melhora a legibilidade e a manutenção, pois torna explícito que essas variáveis estão agrupadas sob um conceito comum.

Conclusão

Para mim, o que mais tirei proveito desse capítulo foi: utilizar de nomes claros e descritivos que revelem o propósito/intenção do seu código.

Entretanto, refatorar para nomes significativos é um processo que não é fácil. Às vezes, você escolhe um nome e pensa "está bom", e então amanhã, você consegue pensar em um outro nome melhor ainda. É um processo que leva tempo. E sempre há código a ser refatorado.

Como você pode melhorar seu código hoje?