A sutil arte de nomear variáveis, métodos, funções, classes, módulos

"Design é, portanto, sobre escolher as abstrações certas. Se você escolher bem, seu código será expressivo, compreensível e flexível, e todos vão amar tanto ele quanto a você. No entanto, se você errar nas abstrações, seu código será complicado, confuso e custoso, e seus colegas programadores vão te odiar." - Sandi Metz

Existem alguns dilemas difíceis em nossa sociedade, como decidir onde ir almoçar hoje, se devo ou não ir para aquela festa de uma pessoa com a qual realmente não tenho 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, ao pensar em uma solução para um problema e já ter toda a lógica de um método em sua cabeça, você simplesmente caiu em um bloqueio mental onde nenhum nome realmente parecia bom, até decidir ir com o primeiro nome que veio à mente, e horas depois, ao refatorar o código, chegou à conclusão de que esse não era o melhor nome? Ou até mesmo nomes de variáveis, métodos e classes que você acabou nomeando mesmo com aquele sentimento de code smell e que nunca mais foram renomeados? Pois é, talvez tenha vindo ao lugar certo.

A ideia deste artigo é 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 isso não substitui a leitura dos mesmos (aliás, eu fortemente recomendo que esses livros sejam lidos, ou pelo menos folheados por você).

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 também 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 The Fuck? traduzindo: Que diabos é isso?) por minuto que uma pessoa desenvolvedora irá pronunciar. Se a quantidade for grande, provavelmente você tem um problema nesse código.

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

Então, como nomear?

A regra geral é que o nome de algo deve ser um nível de abstração mais alto do que a coisa em si.Sandi Metz

No meu dia a dia, como trabalho muito utilizando TDD, muitas vezes não sei o que realmente estou testando 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 a leitura do mesmo, já consigo entender o que realmente aquele teste está testando.

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 vs. comentários

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

Você deveria, por exemplo, olhar para um método e apenas com a 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 explicando-o, 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 revela 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 the fuck? (o nome wtf não revela o seu real significado e por isso é preciso um comentário com a explicação).

Melhor: field :what_the_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ê nunca deve usar abreviações, mas evite-as quando for algum conceito de domínio que não seja tão conhecido pelo público 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, 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 início do artigo. Recomendo fortemente que você olhe alguns style guides criados pela comunidade da linguagem em que você está programando no momento.

Cada linguagem possui seu próprio style guide, que muitas vezes foi criado pela comunidade de desenvolvedoras.

Espero que este artigo tenha ajudado a esclarecer a importância de bons nomes em seu código e como eles podem fazer uma grande diferença na legibilidade e manutenibilidade do mesmo. Boa codificação!