Comentários em R: Como Comentar Seu Código (e Comentar Blocos)

O Símbolo

Um comentário no R começa com #. Daquele caractere até o fim da linha, o R ignora tudo:

# This whole line is a comment. R skips it.
speed_kmh <- 90

speed_ms <- speed_kmh / 3.6  # convert to meters per second

print(speed_ms)

As duas posições são legais: um comentário na própria linha, ou um comentário inline depois do código. Não há nada para fechar - o comentário simplesmente termina onde a linha termina. Um # é suficiente, e # dentro de uma string entre aspas é apenas um caractere, não um comentário:

tag <- "#1 fan"  # the first # is data, this one is a comment
print(tag)

O R Não Tem Comentário Multilinha

Aqui está a resposta para a pergunta que todo iniciante em R uma hora pesquisa no Google: o R não tem sintaxe de comentário de bloco. Não existe /* ... */, nem """docstring""", nem =begin/=end. Cada linha comentada precisa do seu próprio #. Isso é uma simplicidade deliberada da linguagem - e é menos doloroso do que parece, porque o ferramental preenche a lacuna.

A solução do mundo real: o atalho de alternância do seu editor. No RStudio, selecione as linhas e pressione Ctrl+Shift+C (Windows/Linux) ou Cmd+Shift+C (macOS). Cada linha selecionada ganha um prefixo #; pressione de novo e eles somem. É isso que os programadores de R realmente fazem, dezenas de vezes por dia, e vale a pena gravar na memória muscular ainda esta semana. VS Code, Vim e Emacs têm comandos equivalentes de alternar comentário para arquivos R.

O truque do if (FALSE). Como FALSE nunca é verdadeiro, envolver código em if (FALSE) { ... } garante que ele nunca rode:

if (FALSE) {
    expensive_call <- 1 / 0
    cat("you will never see this\n")
}

cat("but you will see this\n")

Conheça-o, mas trate-o como uma curiosidade e não como um hábito, porque ele tem ressalvas reais. O código pulado ainda precisa ser R sintaticamente válido - um comentário de bloco genuíno pode conter qualquer coisa, mas if (FALSE) em volta de uma linha pela metade é um erro de parse que para o script inteiro. Ele também muda o significado silenciosamente se as chaves forem editadas. Quando você quiser linhas desabilitadas, o atalho do editor é mais seguro; quando você quiser que elas sumam, apague-as - é para isso que serve o controle de versão.

O Que Bons Comentários Dizem: Por Quê, Não O Quê

O código já diz o que ele faz. Um comentário que o repete é ruído que acabará ficando desatualizado e começando a mentir:

# Bad: narrates the obvious
x <- x + 1  # add 1 to x

# Good: explains the reason
x <- x + 1  # customer-facing IDs are 1-based, data is 0-based

O segundo comentário carrega informação que o código não pode carregar: por que o incremento existe. Esse é o teste para cada comentário que você escreve - ele explica intenção, contexto ou uma decisão não óbvia? Comentários pagam o próprio sustento nas linhas estranhas: a solução de contorno para um bug de pacote, o deslocamento de um que é intencional, a fórmula que veio de um artigo específico. E lembre-se da regra de manutenção: quando mudar o código, mude o comentário dele, porque um comentário errado é pior do que nenhum.

Se você se pegar escrevendo um comentário para explicar o que uma variável contém, muitas vezes a melhor correção é um nome mais claro - veja variáveis para esse argumento.

Cabeçalhos de Seção que Dobram no RStudio

Scripts de análise ficam longos, e os comentários fazem as vezes de sumário. O RStudio trata uma linha de comentário terminando em quatro ou mais - (ou = ou #) como um cabeçalho de seção:

# Load data ----------------------------------------------------------

# Clean and reshape ----

# Model ====

Cada seção se torna dobrável e aparece no outline do documento do RStudio, de modo que um script de 300 linhas vira uma lista navegável de etapas: carregar, limpar, modelar, plotar. Qualquer um dos caracteres finais funciona desde que haja pelo menos quatro; escolha um estilo e mantenha-o consistente. Mesmo fora do RStudio, comentários de cabeçalho de seção tornam a estrutura de um script visível de relance - é a documentação mais barata que uma análise pode ter.

Comentários roxygen2: #' na Natureza

Lendo código R de outras pessoas - especialmente o código-fonte de pacotes - você encontrará comentários começando com #':

#' Convert a speed from km/h to m/s
#'
#' @param kmh Speed in kilometers per hour.
#' @return Speed in meters per second.
kmh_to_ms <- function(kmh) {
    kmh / 3.6
}

Esses são comentários de documentação do roxygen2. Escritos diretamente acima da definição de uma função, eles são compilados pelo ferramental de pacotes nas páginas de ajuda formais que você lê com ?function_name. As tags (@param, @return) descrevem as entradas e a saída da função. Para o próprio R, uma linha #' é um comentário comum - a convenção só tem poder dentro da cadeia de ferramentas de desenvolvimento de pacotes. Você não precisa escrevê-los até construir um pacote ou documentar suas próprias funções a sério; por enquanto, apenas reconheça-os para que o código-fonte de pacotes não pareça misterioso.

O Que Você Leva Daqui

• # inicia um comentário; ele vai até o fim da linha, seja a linha toda comentário ou código-e-depois-comentário.
• O R não tem comentário multilinha - alterne blocos com Ctrl/Cmd+Shift+C no RStudio, e reserve if (FALSE) {} para código sintaticamente válido que você raramente pula.
• Comente o porquê, não o o quê - e atualize os comentários quando o código mudar.
• Comentários # Section name ---- dão ao RStudio seções dobráveis e dão aos leitores um mapa do script.
• Linhas #' são comentários de documentação do roxygen2 que se tornam páginas de ajuda de pacotes.

A seguir: variáveis - como criá-las com <-, nomeá-las bem e como o R trata os valores que elas guardam.