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)

两种位置都是合法的：注释单独占一行，或者作为行内注释写在代码后面。注释不需要结束符号，行结束了注释就结束了。一个 # 就够了，而且引号字符串里的 # 只是一个普通字符，不是注释：

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 程序员每天都要这样做几十次，值得这周就把它练成肌肉记忆。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) 里有一行写了一半的代码，就会产生解析错误，整个脚本都会停下来。而且一旦大括号被改动，它的含义也会悄悄改变。想临时禁用某些行时，用编辑器快捷键更安全；想彻底删掉它们时，就直接删除，版本控制就是为此而存在的。

好的注释写什么：写为什么，而不是写做什么

代码本身已经说明了它在做什么。重复代码内容的注释只是噪音，迟早会过时，开始误导人：

# 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

第二条注释包含了代码无法表达的信息：这个加一为什么存在。你写的每一条注释都可以用这个标准检验：它是否解释了意图、背景或一个不那么显然的决定？注释最有价值的地方是那些奇怪的代码行：为绕过某个包的 bug 而写的变通代码、故意为之的差一、来自某篇特定论文的公式。还要记住维护的原则：修改代码时，同时修改它的注释，因为错误的注释比没有注释更糟。

如果你发现自己在写注释来解释某个变量存的是什么，更好的办法往往是起一个更清楚的名字，详见变量。

RStudio 中可折叠的分节标题

分析脚本会越写越长，注释同时也可以充当脚本的目录。RStudio 会把以四个或更多 -（或 =、#）结尾的注释行当作分节标题：

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

# Clean and reshape ----

# Model ====

每一节都可以折叠，并会出现在 RStudio 的文档大纲中，于是一个 300 行的脚本就变成了一份可以导航的步骤清单：加载、清洗、建模、画图。结尾用哪种字符都可以，只要至少有四个；选一种风格并保持一致。即使不用 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) {} 只留给偶尔需要跳过、语法又合法的代码。
• 注释写为什么，而不是做什么；代码改了，注释也要跟着改。
• # Section name ---- 这样的注释让 RStudio 生成可折叠的分节，也给读者一张脚本地图。
• #' 行是 roxygen2 文档注释，会变成包的帮助页面。

下一篇：变量，用 <- 创建变量、起个好名字，以及 R 如何对待变量中保存的值。