Importância do style guide e sua aplicação no Ruby

Published in

Prevision Tech

5 min readJan 25, 2023

Aprender uma nova linguagem de programação é sempre um desafio. É um mundo totalmente novo. Precisamos configurar o ambiente, descobrir quais os frameworks e quais as melhores libs utilizar para os nossos objetivos. Acreditamos que nosso código só vai ser realmente bom depois de muitas linhas de código escritas. Bom, isso não deixa de ser verdade. Contudo, é possível e aconselhável nos preocuparmos em escrever um bom código desde o início dos nossos estudos em uma nova linguagem. Para isso temos os style guides.

Style guides

Os style guides, na área de desenvolvimento de software, são uma coleção de boas práticas que buscam, além de padronizar a escrita do código, aumentar a qualidade do desenvolvimento. Geralmente são criados pela comunidade open-source e possuem as diretivas do que se é esperado de um bom programador na linguagem/framework escolhida.

Os style guides não são exclusividade do mundo do desenvolvimento. Podemos citar o livro The Elements of Style, de William Strunk Jr. como um dos precursores dos guias de estilo de escrita. O livro nos mostra como termos uma boa escrita e composição, dando dicas muito importantes como não utilizar palavras desnecessárias e utilizar voz ativa. O livro é considerado um dos 100 livros mais influentes da língua inglesa pela revista Time.

No mundo do desenvolvimento também temos um livro que dita as regras dos style guides. A obra The Elements of Programming Style, de Brian W. Kernighan e P. J. Plauger é a grande referência para a defesa da utilização de style guides na programação. Com a premissa de que softwares devem ser escritos não pensando apenas na resolução do problema em si, mas também em facilitar a legibilidade para os humanos, o livro nos dá dicas que, mesmo tendo sido publicadas originalmente em 1974, seguem muito importantes e que podem alavancar a qualidade do seu código.

Agora que já sabemos o que são style guides e como eles são importantes, vamos ver algumas dicas para aplicarmos na linguagem Ruby.

Aplicação na linguagem Ruby

1. Escrever o código em inglês

Talvez esse você já saiba. A língua inglesa é a linguagem universal no mundo do desenvolvimento. As principais documentações estão em inglês, os principais softwares do mundo foram escritos utilizando inglês nas variáveis, classes, métodos e afins. As palavras reservadas das linguagens são em inglês. Misturar o inglês natural da linguagem com o nosso idioma nativo vai diminuir a legibilidade do seu código. Portanto, é importante estarmos alinhados com essa prática e caso você ainda não escreva seus códigos em inglês, comece agora!
Exemplo:

# Ruim
name = "José"
idade = 32
if deletado?
 ...
end

# Bom
name = "José"
age = 32
if deleted?
  ...
end

2. Evitar métodos auxiliares em funções/métodos que retornam booleano

No Ruby temos um padrão para a escrita de métodos que retornam um valor booleano, que consiste em utilizar “?” como sufixo. Por conta deste padrão, não é uma boa prática utilizar verbos auxiliares como can, has, is, etc.
Exemplo:

# Ruim
def is_admin?(user)
  ...
end

# Bom
def admin?(user)
  ...
end

3. Utilizar underline em números grandes

Quando declaramos uma variável com um número grande, como por exemplo um milhão (1.000.000), podemos facilitar a leitura do número com a utilização de underlines (“_”).
Exemplo:

# Ruim
price = 1000000

# Bom
price = 1_000_000

**4. Evitar return explícito**

Exceto em casos de fluxo de controle, não se deve utilizar return em métodos/funções. Em vez disso, é aconselhado utilizar o retorno implícito característico do Ruby.
Exemplo:

# Ruim
def welcome(name)
  return "Welcome, #{name}"
end

# Bom
def welcome(name)
  "Welcome, #{name}"
end

**5. Utilizar begin implícito ao utilizar exceções**

Quando for possível, é recomendado utilizarmos o begin implícito, para deixar o código mais fácil de ser lido.
Exemplo:

# Ruim
def divide(x, y)
  begin
    x / y
  rescue
    handle_error
  end
end

# Bom
def divide(x, y)
  x / y
rescue
  handle_error
end

6. Estrutura de classes

Há uma estrutura que é indicada para manter suas classes consistentes. A sequência de definições é:

extend/include/prepend;
classes internas;
valores constantes;
macros de atributos;
demais macros;
métodos de classe públicos;
inicialização;
métodos públicos;
métodos protegidos;
métodos privados.

Nem sempre iremos utilizar todos esses tipos de definição nas nossas classes, contudo é importante sabermos os principais pontos para que possamos escrever nossas classes de maneira mais consistente.
Exemplo:

class Person
  extend SomeModule
  include AnotherModule
  prepend YetAnotherModule

  class CustomError < StandardError
  end

  SOME_CONSTANT = 20

  attr_reader :name

  validates :name

  def self.some_method
  end

  def initialize
  end

  def some_method
  end

  protected

  def some_protected_method
  end

  private

  def some_private_method
  end
end

7. Anotações em comentários

Embora o nosso querido Uncle Bob nos diga que um comentário é um grande sinal que nosso código precisa ser melhorado, em algumas situações eles são necessários. E para que possamos dar mais sentido a esses comentários, podemos utilizar as seguinte anotações:

TODO: algo que deve ser feito posteriormente;
FIXME: algo que deve ser corrigido;
OPTIMIZE: algo que deve ser otimizado;
HACK: indicação de code smells;
REVIEW: trecho que deve ser confirmado se está funcionando corretamente.

Esse comentários devem ser escritos na linha imediatamente acima da linha que queremos adicionar a anotação, além de usarmos o padrão ANOTAÇÃO: comentário (tipo da anotação, seguido de “:” e espaço, para então o conteúdo do comentário).
Exemplo:

# Ruim
def profile_texts(profiles)
 profiles_composed = []
 profiles.each do |profile| # TODO refatorar para utilizar .map
   profiles_composed.push("#{profile.name} - #{profile.age}")
 end
end


# Bom
def profile_texts(profiles)
 profiles_composed = []


 # TODO refatorar para utilizar .map
 profiles.each do |profile|
   profiles_composed.push("#{profile.name} - #{profile.age}")
 end
end

Considerações finais

Utilizar um style guide é uma ótima ferramenta para te auxiliar no aprendizado de uma nova linguagem. Se você está iniciando no Ruby ou se já trabalha faz um tempo e não conhecia esse style guide, vale muito a pena conhecer. Clique aqui e saiba mais.

É importante se dizer que não é preciso seguir cegamente um style guide. É uma ferramenta para nos auxiliar a melhorar e padronizar nosso código, contudo não detém todas as respostas para todos os cenários. Utilize o que for melhor para o entendimento do seu time.

REFERÊNCIAS

Ruby Style Guide — https://rubystyle.guide/
The Elements of Style — https://en.wikipedia.org/wiki/The_Elements_of_Style
The Elements of Programming Style — https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style
Comment annotations — https://relishapp.com/womply/ruby-style-guide/docs/comments/annotations