5.5 Boas práticas para códigos de boa qualidade

Uma codificação em bom estilo é como usar a pontuação corretamente. Você pode até escrever sem usá-la, mas ela certamente deixa as coisas mais fáceis de ler.

— Hadley Wickham

A medida que a complexidade dos códigos aumenta, você perceberá que a organização é imprescindível para rápida compreensão dele por você mesmo no futuro, pelos usuários e colaboradores. Um bom código não deve focar somente no desempenho de execução, mas também em sua simplicidade, legibilidade, o que inerentemente facilita sua manutenção por outros contribuidores.

Para deixar seu código compreensível uma boa referência é o Guia de estilo de codificação tidyverse. Um guia bastante utilizado pela comunidade e adotado pela Google.

A aplicação de todas as regras de formatação de código do tidyverse podem ser difíceis de ser lembradas. Mas este problema pode ser amenizado com o pacote styler que fornece funções para estilizar o seu código no padrão tidyverse. Para utilizá-lo, instale o pacote styler.

install.packages("styler")

As funções são acessíveis Através do menu Addins do RStudio e incluem as opções de: estilizar um arquivo e uma região destacada do código (Figura 5.2).

Exemplo de aplicação do Estilo de codificação tidyverse.

Figura 5.2: Exemplo de aplicação do Estilo de codificação tidyverse.

A convenção de estilo dos seus códigos é uma escolha sua. Por exemplo, alguns preferem usar a notação camelo (nomeVariavel) ao invés da notação cobra (nome_variavel) na definição do nome de variáveis e funções. Eu indico seguir o estilo tidyverse (notação cobra), mas você pode optar por outro. O mais importante é ser consistente e não fazer lambança.

5.5.1 Nomes de variáveis

“Há somente duas coisas difíceis em Ciência da Computação: invalidação de cache e escolher nomes para as coisas.”

— Phil Karlton

Na seção (5.3), vimos como criar variáveis. Este procedimento, implica em definir um nome para variável. Dar nomes claros, objetivos e coerentes para variáveis, funções, e argumentos é difícil.

Nomes de variáveis com significado.

Figura 5.3: Nomes de variáveis com significado.

A falta de clareza as vezes é compensada por excesso de comentários no código. Porém, hoje em dia, a prática de comentar o máximo possível está obsoleta e danosa.

O bom código é sua própria melhor documentação. Quando você for a adicionar um comentário, se pergunte, “Como eu posso melhorar o código para que o este comentário não seja necessário?” Melhore o código e então o documente para torná-lo ainda mais claro.

— Steve McConnell

De forma geral, podemos listar os seguintes cuidados ao nomear variáveis no :

  • usar nomes claros, objetivos e coerentes

  • não iniciar com um número, ponto (.) ou sublinhado (_) e não conter espaços

  • não usar acentos e caracteres especiais

    ^, !, $, @, +, -, /, ou *

  • evitar o uso de nomes reservados do (funções internas, constantes e etc):

    c q  s  t  C  D  F  I  T  diff  exp  log  mean  pi  range  rank  var

FALSE  Inf  NA  NaN  NULL TRUE 

break  else  for  function  if  in  next  repeat  while

  • usar <- para atribuição (colocar um espaço antes e depois) e deixe o = para argumentos de funções.

  • não colocar ; no final de uma linha e evite vários comandos na mesma linha.

  • usar somente letras minúsculas, números (após a primeira letra do nome). Use o _ ou sublinhado para separar palavras dentro de um nome de variável longo(caso cobra).