Guia de Estilo R do Google (Google’s R Style Guide)

[Pedro Brantes]

R é uma linguagem de programação de alto nível usada principalmente para computação estatística e gráficos. O objetivo do Guia de Estilo de Programação R é tornar nosso código R mais fácil de ler, compartilhar e verificar. O Guia de Estilo R do Google é um fork do Tidyverse Style Guide de Hadley Wickham com licença. As modificações do Google foram desenvolvidas em colaboração com a comunidade interna de usuários de R. O restante deste documento explica as principais diferenças do Google com o guia Tidyverse, e por que essas diferenças existem. (Traduzido para PT-BR por Pedro Brantes)

Sintaxe

Convenções de nomenclatura

O Google prefere identificar funções com BigCamelCase para distingui-las claramente de outros objetos.

# Good
DoNothing <- function() {
  return(invisible(NULL))
}

Os nomes das funções privadas devem começar com um ponto. Isso ajuda a comunicar tanto a origem da função quanto seu uso pretendido.

# Good
.DoNothingPrivately <- function() {
  return(invisible(NULL))
}

Anteriormente, recomendávamos nomear objetos com dot.case. Estamos nos afastando disso, pois cria confusão com métodos S3.

Não use attach()

As possibilidades de criar erros ao usar attach() são numerosas.

Pipes

Atribuição à direita

Não apoiamos a atribuição à direita. (->)

# Bad
iris %>%
  dplyr::summarize(max_petal = max(Petal.Width)) -> results

Esta convenção difere substancialmente das práticas em outras linguagens e torna mais difícil ver no código onde um objeto é definido. Por exemplo, é mais fácil procurar por foo <- do que procurar por foo <- e -> foo (possivelmente dividido em linhas).

Use retornos explícitos

Não confie no recurso de retorno implícito do R. É melhor deixar claro sua intenção de return() um objeto.

# Good
AddValues <- function(x, y) {
  return(x + y)
}

# Bad
AddValues <- function(x, y) {
  x + y
}

Namespaces qualificados

Os usuários devem explicitamente qualificar os namespaces para todas as funções externas.

# Good
purrr::map()

Desencorajamos o uso da tag @import Roxygen para trazer todas as funções para um NAMESPACE. A Google possui uma base de código R muito grande e importar todas as funções cria muito risco de colisão de nomes.

Embora haja uma pequena penalidade de desempenho ao usar "::", torna mais fácil entender as dependências no seu código. Existem algumas exceções a essa regra.

• As funções infixas (%name%) sempre precisam ser importadas.
  
• Certos pronomes rlang, especialmente .data, precisam ser importados.
  
• Funções dos pacotes R padrão, incluindo datasets, utils, grDevices, graphics, stats e methods. Se necessário, você pode @import o pacote completo.
  

Ao importar funções, coloque a tag @importFrom no cabeçalho Roxygen acima da função onde a dependência externa é usada.

Documentação

Documentação em nível de pacote

Todos os pacotes devem ter um arquivo de documentação do pacote, em um arquivo packagename-package.R.