Carlos Brando

Nome do Jogo

Rails Way #3: Nomes de métodos e variáveis devem ser óbvios

Não sou uma pessoa supersticiosa, mas hoje é sexta-feira (13) e é melhor não abusar, então vamos manter a tradição e comentar sobre mais um rubismo, ou se preferir, mais uma boa prática de programação que todos os desenvolvedores deveriam adotar independente da linguagem que usem.

Dar nomes para classes, módulos, métodos e variáveis é uma tarefa complicada em alguns casos. Com certeza você em algum momento de sua carreira já ficou na dúvida sobre que nome dar a um determinado método ou variável. Talvez até mesmo apelou para algum colega de trabalho em busca de alguma sugestão.

A regra é: o nome de uma classe, módulo, método ou variável deve ser o mais óbvio possível. Em muitos casos, um programador totalmente concentrado no código que está escrevendo não se apercebe de que o que lhe parece óbvio naquele momento, não será tão óbvio na segunda-feira, depois de um fim de semana com a família. E se ele próprio pode ficar um pouco perdido com nomes estranhos e abreviações, imagine quando um outro programador sem o contexto necessário for fazer uma manutenção naquele código.

Andy Lester em 2004 escreveu em seu artigo “The world’s two worst variable names”, que o pior nome para se dar a uma variável é data. Como no exemplo abaixo:

data = User.find(10)
puts "Nome: = #{data.name}"

Eu já vi muito este tipo de coisa, e tenho certeza de que você também. Mas que droga de nome é este? É óbvio que o que está armazenado em uma variável é um dado (data), mas que tipo de dado, é a pergunta a ser feita. Neste caso especifico renomear a variável para user já faria uma enorme diferença. Nomes como data, ret e temp não querem dizer nada.

Agora vem a melhor (ironicamente) parte, o segundo pior nome para se dar a uma variável é data2 e suas variações. Veja só que coisa horrível:

user  = User.find(10)
user2 = User.find(20)
puts "O #{user.name} é amigo do #{user2.name}"

No exemplo acima estou usando um nome descritivo, mas qual é a diferença entre user e user2? Eu preciso ser mais óbvio que isto. No contexto do exemplo acima, alterar a segunda variável para friend, resolveria este problema e tornaria meu código mais descritivo.

Não use abreviações

Não use abreviações, à menos que elas sejam realmente óbvias. E quando eu digo óbvia estou dizendo que deve ser para qualquer um, mesmo alguém que nunca trabalhou em seu código. Não existe problema algum em usar nomes longos e descritivos. Veja por exemplo, o nome deste método:

def thera_class_code_fmt
  # devolve alguma coisa
end

E então? O que este método faz? Para mim parece óbvio, mas você não tem obrigação de saber que ‘thera’ é uma abreviação para therapeutic, assim como ‘fmt’ é para formatted. Não seria melhor se este método se chamasse formatted_therapeutic_class_code?

No próprio Rails podemos encontrar alguns nomes longos e descritivos como convert_number_column_value e class_name_of_active_record_descendant. Em alguns casos nem precisamos olhar a documentação para entender como o método funciona.

Prefixos não são necessários

Prefixos como str, int e coisas do gênero não são necessários se eu der um nome descritivo à variável. Ao ver uma variável chamada age (idade) logo você deduz que ela deve ser do tipo numérica, assim não seria necessário dar a ela um nome estranho como int_age, ou algo parecido. Podemos dizer o mesmo de uma variável chamada name (nome) que obviamente deve ser um objeto do tipo string.

Use os recursos da linguagem

No Ruby também usamos alguns símbolos em nomes de métodos, como ‘?’ e ‘!’. Um símbolo de interrogação (?) no final no nome indica que aquele método deve retorna um booleano true ou false. O sinal de exclamação (!) informa que o método é destrutivo perigoso, o que pode significar duas coisas: no caso de algo dar errado ele devolverá uma exceção ao invés de um simples false, como nos métodos save e save! do Active Record ou que ele alterará a própria instância do objeto, ao invés de devolver uma nova instância, como nos métodos merge e merge!, por exemplo.

Código bilingue?

Embora não exista uma regra escrita para isto, também sou contra nomear variáveis, métodos ou classe em português. Acho que como todo o código já está em inglês, graças as palavras chaves do Ruby, devemos manter absolutamente tudo em inglês também. Isto não é tão difícil assim, já que você pode fazer uso de tradutores e dicionários (online) para encontrar a melhor descrição para eles.

Pense antes de escolher um nome

Algumas vezes, escolher um bom nome pode parecer difícil, e isto pode acabar roubando um pouco do seu tempo. A dica é que você termine de codificar o seu método primeiro, e depois com o contexto formado em sua mente ficará mais fácil dar um nome descritivo para o método e para as variáveis usadas. Se mesmo assim você ficar na dúvida, inclua um comentário com um TODO no seu código, vá tomar um café e quando você voltar com certeza encontrará um bom nome.

Uma das grandes vantagens que encontramos no Ruby e no Rails é que em ambos é extremamente normal encontrar nomes descritivos e tão curtos quanto possível em classe, módulo, métodos e variáveis. POR FAVOR, NÃO ESTRAGUE ISTO.

Comments