Rのコメント：コードに注釈を付ける方法（複数行のコメントアウトも）

# 記号

Rのコメントは # で始まります。その文字から行末まで、Rはすべてを無視します。

# 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)

どちらの置き方も合法です。コメントだけの行でも、コードの後ろに置くインラインコメントでもかまいません。閉じる必要はありません。コメントは行が終わるところで終わります。# は1つで十分ですし、引用符で囲まれた文字列の中の # は単なる文字で、コメントにはなりません。

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

Rに複数行コメントはない

R初心者がいつか必ず検索する疑問への答えがこれです。Rにはブロックコメントの構文がありません。 /* ... */ も、"""docstring""" も、=begin/=end もありません。コメントにする行にはそれぞれ # が必要です。これは言語として意図的に単純さを保った結果であり、ツールがその隙間を埋めてくれるので、聞こえるほど苦にはなりません。

現実的な解決策：エディタのトグルショートカット。 RStudioでは対象の行を選択して、Ctrl+Shift+C（Windows/Linux）または Cmd+Shift+C（macOS）を押します。選択したすべての行に # が付き、もう一度押せば消えます。Rプログラマーが1日に何十回も実際にやっていることなので、今週のうちに指に覚えさせておく価値があります。VS Code、Vim、Emacsにも、Rファイル向けの同等のコメント切り替えコマンドがあります。

if (FALSE) の小技。 FALSE は決して真にならないので、コードを if (FALSE) { ... } で囲めば絶対に実行されません。

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

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

知っておくのはよいことですが、習慣にするのではなく雑学程度に留めましょう。実際の注意点があるからです。スキップされるコードも文法的に正しい Rでなければなりません。本物のブロックコメントなら何でも入れられますが、書きかけの行を if (FALSE) で囲むとパースエラーになり、スクリプト全体が止まります。また、波かっこが編集されると意味が静かに変わってしまいます。行を無効化したいときはエディタのショートカットのほうが安全ですし、消したいときは削除しましょう。そのためのバージョン管理です。

良いコメントが語ること：What ではなく Why

コードは何をしているかをすでに語っています。それを繰り返すコメントはノイズであり、いずれ内容がずれて嘘をつき始めます。

# 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

2つ目のコメントは、コードには表せない情報——なぜその加算があるのか——を運んでいます。これがコメントを書くたびに問うべきテストです。意図、文脈、あるいは自明でない判断を説明しているか？ コメントが真価を発揮するのは奇妙な行です。パッケージのバグへの回避策、意図的な1つずれ、特定の論文から取ってきた数式など。そして保守のルールを忘れずに。コードを変えたらそのコメントも変えること。間違ったコメントは、コメントがないより悪いからです。

変数が何を保持しているかを説明するコメントを書きそうになったら、たいていはもっと明確な名前を付けるほうが良い解決策です。その議論は変数にあります。

RStudioで折りたためるセクション見出し

分析スクリプトは長くなりがちで、コメントはその目次にもなります。RStudioは、4つ以上の -（あるいは = や #）で終わるコメント行をセクション見出しとして扱います。

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

# Clean and reshape ----

# Model ====

各セクションは折りたためるようになり、RStudioのドキュメントアウトラインにも表示されるので、300行のスクリプトが「読み込み、整形、モデリング、作図」というたどれる手順一覧に変わります。末尾の文字はどれでも、4つ以上あれば機能します。1つのスタイルを選んで一貫させましょう。RStudio以外でも、セクション見出しのコメントはスクリプトの構造を一目で見せてくれます。分析にとって最も安上がりなドキュメントです。

roxygen2コメント：野生の #'

他人のRコード、とりわけパッケージのソースを読むと、#' で始まるコメントに出会います。

#' 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
}

これらは roxygen2 のドキュメントコメントです。関数定義の直上に書かれ、パッケージのツールによって ?function_name で読む正式なヘルプページにコンパイルされます。タグ（@param、@return）は関数の入力と出力を説明します。R自体にとって #' の行はただのコメントで、この慣習が力を持つのはパッケージ開発のツールチェーンの中だけです。パッケージを作るか、自分の関数を本格的にドキュメント化するまでは書く必要はありません。今のところは、パッケージのソースコードを見て不思議に思わない程度に見分けられれば十分です。

この記事のまとめ

• # がコメントの始まりで、行末まで続きます。行全体がコメントでも、コードの後ろのコメントでも同じです。
• Rに複数行コメントはありません。RStudioのCtrl/Cmd+Shift+Cでブロックを切り替え、if (FALSE) {} は文法的に正しくめったに飛ばさないコードのために取っておきましょう。
• コメントすべきは What ではなく Why。そしてコードを変えたらコメントも更新すること。
• # Section name ---- のコメントは、RStudioに折りたたみ可能なセクションを与え、読み手にはスクリプトの地図を与えます。
• #' の行はroxygen2のドキュメントコメントで、パッケージのヘルプページになります。

次は変数です。<- での作成、良い名前の付け方、そして変数が保持する値をRがどう扱うのかを見ていきます。