R中的文档字符串有缺点吗？

【问题标题】：Are there downsides with docstrings in R?R中的文档字符串有缺点吗？
【发布时间】：2012-11-29 23:57:19
【问题描述】：

我不喜欢 cmets 的自动缩进 ESS（Emacs Speaks Statistics）模式，因为它位于最右侧。

normalize <- function(values){
                                        # comment
  return(2* values / (max(values) - min(values)) )
}

Python 还为 cmets 使用文档字符串。我在 R 中玩弄它。

normalize <- function(values){
  "comment
   line 2 of comment"
  return(2* values / (max(values) - min(values)) )
}

我相信我也可以修复 cmets 的 ESS 缩进，但我喜欢 multiline 的想法厘米。 GNU R 中的文档字符串有什么缺点吗？

【问题讨论】：

FWIW：ESS ## 中的两个注释字符将缩进到“正确”的缩进级别。

标签： r ess

【解决方案1】：

以## 而不是# 开头的评论将根据当前缩进级别自动缩进。

j <- function(x) {
                                        # One hash auto-indents to column 40 
    ## Two hashes auto-indent to current level
### Three hashes auto-indent to BOL
    rnorm(x)
}

【讨论】：

它们将被缩进，但它们将与当前的缩进级别保持一致。
@Jonas -- 我能马上想到的三个缺点。 (1) # 更突出：当使用" 时，每一行都没有简单的标记来告诉你它是否是评论。 (2) 包源代码中以# 开头的注释在函数体中对最终用户不可见。描述实现细节的注释可以出现在一个地方，而不会弄乱另一个地方。 (3) 以# 开头的评论可以包含带引号的字符串。