Tidyverse Style Guide

📁 FILES (Arquivos)

1. Nomenclatura de Arquivos

Use apenas letras minúsculas, números e underscores (_) ou hífens (-). Nomes devem ser significativos e descritivos.

✓ Correto

01_importar_dados.R
funcoes_auxiliares.R
modelo_regressao.R

✗ Incorreto

Análise Final.R
dadosTemp.R
foo.R

2. Prefixos Numéricos

Use prefixos numéricos para indicar ordem de execução.

✓ Correto

00_download.R
01_processar.R
02_visualizar.R

✗ Incorreto

download.R
processar.R
# Sem ordem

3. Estrutura Interna

Organize: (1) Cabeçalho/descrição, (2) Pacotes, (3) Funções, (4) Código. NUNCA use install.packages() em scripts.

✓ Correto

# Análise - 2025
# Autor: Nome

library(tidyverse)

calc <- function(x) {...}

dados <- read_csv(...)

✗ Incorreto

install.packages("tidyverse")
x <- 5
library(tidyverse)
# Código misturado

🔗 PIPES (incluindo ggplot2)

1. Operador de Pipe

Use |> (pipe nativo, R ≥ 4.1) ou %>% (magrittr). Preferência: |> para código novo.

✓ Correto

resultado <- dados |>
  filter(ano == 2025) |>
  group_by(regiao) |>
  summarise(total = sum(valor))

✗ Incorreto

resultado <- summarise(
  group_by(
    filter(dados, ano == 2025),
    regiao
  ), total = sum(valor)
)

2. Formatação de Pipes

Uma operação por linha. Quebre linha DEPOIS do pipe (|>), nunca antes. Indente com 2 espaços.

✓ Correto

dados |>
  filter(status == "ativo") |>
  mutate(
    valor_corrigido = valor * fator
  ) |>
  select(id, valor_corrigido)

✗ Incorreto

# Pipe no INÍCIO (ERRADO!)
dados 
  |> filter(status == "ativo")
  |> select(id, valor)

3. Atribuição com Pipes

Atribuição (<-) sempre no início, nunca no final com ->.

✓ Correto

dados_proc <- dados_brutos |>
  filter(!is.na(valor)) |>
  mutate(log_valor = log(valor))

✗ Incorreto

dados_brutos |>
  filter(!is.na(valor)) ->
    dados_proc

4. Quando Usar Pipes

Use: sequências de 2+ operações lineares. Evite: pipes muito longos (>10 etapas), múltiplos inputs/outputs.

✓ Correto

# Dividir em etapas
dados_limpos <- dados |>
  filter(!is.na(valor))

dados_final <- dados_limpos |>
  group_by(categoria) |>
  summarise(total = sum(valor))

✗ Incorreto

# Pipe desnecessário
media <- dados$valor |> mean()

# Pipe muito longo
# Difícil de debugar

5. ggplot2: Uso de +

ggplot2 usa + (não pipes!). Espaço antes do +, quebra de linha depois. Uma camada por linha.

✓ Correto

ggplot(dados, aes(x = x, y = y)) +
  geom_point() +
  geom_smooth(method = "lm") +
  labs(title = "Título") +
  theme_minimal()

✗ Incorreto

# + no INÍCIO (ERRADO!)
ggplot(dados, aes(x = x, y = y))
  + geom_point()
  + theme_minimal()

6. ggplot2: Combinação com Pipes

Combine pipes com ggplot2: use |> para preparar dados, depois + para camadas.

✓ Correto

iris |>
  filter(Species == "setosa") |>
  ggplot(aes(x = Sepal.Width, 
             y = Sepal.Length)) +
  geom_point() +
  theme_minimal()

✗ Incorreto

# Filtro dentro do ggplot
ggplot(
  filter(iris, Species == "setosa"),
  aes(x = Sepal.Width, y = Sepal.Length)
) + geom_point()

7. ggplot2: Argumentos Longos

Se argumentos não couberem em uma linha, coloque cada um em sua própria linha com indentação.

✓ Correto

ggplot(iris, aes(
  x = Sepal.Width,
  y = Sepal.Length,
  color = Species
)) +
  geom_point() +
  labs(
    x = "Sepal width, cm",
    y = "Sepal length, cm"
  )

✗ Incorreto

ggplot(iris, aes(x = Sepal.Width, y = Sepal.Length, color = Species)) +
  geom_point() +
  labs(x = "Sepal width, cm", y = "Sepal length, cm")
# Linha muito longa

🎨 SYNTAX (Sintaxe)

1. Nomenclatura: snake_case

Use snake_case para objetos, variáveis e funções. Evite camelCase, PascalCase ou pontos.

✓ Correto

dados_vendas <- read_csv(...)
taxa_conversao <- 0.15
numero_clientes <- 1000

✗ Incorreto

dadosVendas <- read_csv(...)
TaxaConversao <- 0.15
numero.clientes <- 1000

2. Espaçamento

Use espaços ao redor de operadores e depois de vírgulas. Não use espaços dentro de parênteses/colchetes ou antes de parênteses em funções.

✓ Correto

x <- 5
media <- mean(x, na.rm = TRUE)
dados[1, 5]
if (x > 10) print("alto")

✗ Incorreto

x<-5
media<-mean(x,na.rm=TRUE)
log (x)
if(x>10)print("alto")

3. Operador de Atribuição

Use sempre <- para atribuição, nunca =.

✓ Correto

x <- 5
resultado <- calcular(dados)

✗ Incorreto

x = 5
resultado = calcular(dados)

💡 Atalho RStudio: Alt + - (Win/Linux) ou Option + - (Mac)

4. Indentação

Use 2 espaços (nunca tabs). Quebre linhas longas (máx 80 caracteres).

✓ Correto

dados_filtrados <- filter(
  dados,
  ano >= 2020,
  !is.na(valor)
)

✗ Incorreto

dados_filtrados <- filter(dados, ano >= 2020, !is.na(valor))

# Indentação inconsistente

5. Aspas

Prefira aspas duplas (") para strings.

✓ Correto

nome <- "João Silva"
arquivo <- "dados/vendas.csv"

✗ Evite

nome <- 'João Silva'
arquivo <- 'dados/vendas.csv'

⚙️ FUNCTIONS (Funções)

1. Quando Criar Funções

Se você copiou e colou código mais de 2 vezes, crie uma função! Regra: DRY (Don't Repeat Yourself).

2. Nomes de Funções

Use verbos descritivos em snake_case. Evite nomes genéricos ou muito curtos.

✓ Correto

calcular_media_movel()
limpar_dados_ausentes()
validar_cpf()
gerar_relatorio()

✗ Incorreto

f()
minha_funcao()
dados()  # substantivo
calc()   # muito curto

3. Ordem dos Argumentos

Argumentos obrigatórios primeiro, depois opcionais com valores padrão.

✓ Correto

calcular_taxa <- function(
  valor_atual,      # obrigatório
  valor_anterior,   # obrigatório
  casas = 2         # opcional
) { ... }

✗ Incorreto

calcular_taxa <- function(
  casas = 2,        # opcional primeiro!
  valor_atual,
  valor_anterior
) { ... }

4. Retorno de Funções

Use return() apenas para retornos antecipados. A última expressão é o retorno implícito.

✓ Correto

somar <- function(a, b) {
  a + b  # implícito
}

validar <- function(x) {
  if (x < 0) return(NA)
  if (x < 18) return("menor")
  "maior"  # implícito
}

✗ Incorreto

somar <- function(a, b) {
  resultado <- a + b
  return(resultado)  # desnecessário
}

validar <- function(x) {
  if (x < 18) {
    return("menor")
  } else {
    return("maior")  # desnecessário
  }
}

5. Comentários em Funções

Explique o "porquê", não o "o quê". Documente propósito, argumentos e retorno.

✓ Correto

# Usa log1p() para evitar -Inf
# quando x = 0
transformar <- function(x) {
  log1p(x)
}

✗ Incorreto

# Transforma valores
transformar <- function(x) {
  log1p(x)  # aplica log1p
}

📊 Tidyverse Style Guide