Adriano Lisboa Blog
Pensamentos, histórias e ideias.

A Sutil Arte De Nomear Variáveis, Métodos e Classes

Design is thus about picking the right abstractions. If you choose well, your code will be expressive, understandable and flexible, and everyone will love both it and you. However, if you get the abstractions wrong, your code will be convoluted, confusing, and costly, and your programming peers will hate you.

  • Sandi Metz

Existem alguns dilemas difíceis da nossa sociedade, como decidir onde ir almoçar hoje, se devo ou não ir para aquela festa de uma pessoa que você realmente não tem tanta afinidade, e um mais comum para nós pessoas desenvolvedoras é o dilema de como nomear variáveis, métodos e classes.

Pare e pense por um instante, qual foi a última vez que você ao estar pensando em uma solução para um problema e já tenha toda a lógica de um método em sua cabeça, mas nomear método você simplesmente cai em um bloqueio mental onde nenhum nome realmente parece bom, até decidir ir com o primeiro, e horas depois ao refatorar o código você chega a conclusão que esse não era o melhor nome. Ou até mesmo nomes de variáveis, métodos e classes em que você acaba nomeando mesmo com aquele sentimento de code smell e que nunca mais foram renomeadas ? Pois é, talvez tenha vindo ao lugar certo.

A ideia desse artigo é de tentar ser um resumo de boas práticas de livros como Código Limpo do Uncle Bob e 99 Bottles of OOP da Sandi Metz, mas que não substitui a leitura dos mesmos (alias eu fortemente recomendo que esses livros sejam lidos, ou pelo menos folheados por você).

image-1
Figura 1: Martin Fowler / Two Hard Things - Cortesia: https://martinfowler.com/bliki/TwoHardThings.html


A importância de bons nomes

Ter bons nomes não só vai facilitar o entendimento futuro de um código, mas vai ajudar as pessoas desenvolvedoras a conseguirem dar manutenção no mesmo evitando a famosa métrica WTF/Minute cunhada por Uncle Bob no livro Código Limpo.

A ideia da métrica é a seguinte: ao se deparar com um código, qual a quantidade de WTF (What That Fuck? traduzindo: que porra é essa?) por minutos que uma pessoa desenvolvedora irá pronunciar. Se a quantidade for grande, provavelmente você tem um problema nesse código.

image-2
Figura 2: Métrica WTFs/m - Cortesia: https://www.osnews.com/story/19266/wtfsm/


Então como nomear ?

The general rule is that the name of a thing should be one level of abstraction higher than the thing itself.

  • Sandi Metz

No meu dia a dia como trabalho muito utilizando TDD, muitas vezes ao começar um teste não sei realmente oque quero testar e como nomear o método que vai ser testado. Uma das táticas que uso é criar o teste e o respectivo método com um nome qualquer (no geral acabo usando nomes de frutas, como banana, pera, etc...). Ao terminar a implementação do teste e fazendo uma leitura do mesmo eu já consigo entender seu significado e como nomeá-lo.

Exemplo:

it "banana" do
    first_number = 1
    second_number = 2
    banana = Math.banana(first_number, second_number)

    expect(banana).to eq(3)
end

Poderíamos reescrever o teste acima da seguinte maneira após seu entendimento:

it "sums two numbers" do
    first_number = 1
    second_number = 2
    summed_number = Math.sum(first_number, second_number)

    expect(summed_number).to eq(3)
end

Nomes significativos v.s. comentários

Uma variável, método, classe deveriam ter um nome que seja significativo e que responda a perguntas como: motivo de sua existência, o que realmente ela faz e como é ou será usado.

Você deveria por exemplo olhar para um método e apenas com a sua leitura de sua chamada ter um entendimento básico de qual ação e resultado são resultantes desse método. Se são necessários comentários o explicando, talvez o nome não esteja revelando a sua real intenção.

Exemplo:

Ruim: field :date, type: String # data de nascimento (o nome date não releva o seu real significado e por isso é preciso um comentário com a explicação).

Melhor: field :birth_date, type: String


Uso de abreviações

Prefira nomes autoexplicativos e com significado a abreviações, uma pessoa que recém chegou ao projeto pode não entender ainda o domínio e ficar perdida em abreviações.

Exemplo:

Ruim: field :wtf, type: String # what that fuck? (o nome** wtf** não releva o seu real significado e por isso é preciso um comentário com a explicação).

Melhor: field :what_that_fuck, type: String (é apenas uma brincadeira... você não deveria nomear métodos com palavrões, mas serve de exemplo de abreviatura).

Não estou dizendo que você não deva usar abreviações nunca, mas evite-as quando for algum conceito de domínio que não seja tão conhecido pelo publico em geral, por exemplo uma variável poderia se chamar url em vez de uniform_resource_locator.


Style Guides

Style guides (ou guias de estilo), são nada mais que como o nome já diz, um guia criado por uma empresa ou pessoa de boas práticas a serem seguidas em uma determinada linguagem.

Listei acima algumas boas práticas extraídas dos livros que citei no começo do artigo, recomendo fortemente que você olhe alguns style guides criados pela comunidade da linguagem em que você está programando no momento.

Para Java, por exemplo, existem style guides do utilizados pelo Twitter, pela Google (Nota: a Google mantém todos os style guides de linguagens em um único lugar), além de vários outros.

Para Ruby existem os style guides do Rubocop, utilizados pelo Airbnb, pelo Shopify, entre outros.

Para Elixir existe um bem famoso criado por Christopher Adams e mantido pela comunidade no GitHub, além de vários outros.

Para Python por exemplo existe o PEP 8.

E por aí vai... cada linguagem possui seu próprio style guide e que muitas vezes foi criado pela comunidade de desenvolvedoras.


Agradecimentos

Um obrigado especial para Vitor Albuquerque e Lorena Souza por terem revisado o artigo :)

Author image
Brasil
I'm a Developer with good experience on design and architecture of software projects, agile methodologies, continuous integration, continuous deployment and continuous delivery.