Google的R样式建议规范

翻译者：小T（殷腾飞）

R 是一门高级语言，主要用于统计计算和成像。这篇“R编程样式指南“的目的是使您的R程序变得简洁易读，便于分享，检验。下面的规则是由google的R社区所有成员共同讨论设计的。

总结: R代码样式规则

1. 文件名: 由.R结尾
2. 标识符（Identifiers）: variable.name（变量.名称）, FunctionName（函数名）, kConstantName（常量名）
3. 每行代码长度: 最大80字符
4. 缩进: 两个空格，没有tab
5. 行间距
6. 花括号{}: 第一个"{"和代码同行, 最后一个"}"自己单独一行
7. 赋值: 使用 <-, 而不是 =
8. 分号: 不使用
9. 主要布局与顺序
10. 注释指南: 所有注释由 #开始，后接一个空格;行内注释需要在 #之前加入两个空格
11. 函数（function）定义与调用（call）
12. 函数文档攥写
13. 函数实例
14. TODO 样式: TODO(用户名)

总结：R代码样式规则

1. attach: 避免使用
2. 函数: 错误信息要用 stop()抛出
3. 对象（Objects）和方法（Methods）: 尽可能少用S4的对象和方法;绝不混用S3和S4

标志与命名

文件名

文件名称需要由 .R 结束，并且具有一定字面意义。
正面实例: predict_ad_revenue.R
负面实例: foo.R

标识符

在标识符中不要使用下划线 ( _ ) 或者连字符号。 ( - ) 标识符请按照下面惯例命名. 变量名称所有字母需要小写，并且单词之间由 (.)分割; 函数名称所有单词首字大写，并且没有用点进行分割。 (CapWords);常数的命名与函数类似，但是首字母加小写k k.

• variable.name（变量名）
  正面实例: avg.clicks
  负面实例: avg_Clicks , avgClicks
• FunctionName（函数名称）
  正面实例: CalculateAvgClicks
  负面实例: calculate_avg_clicks , calculateAvgClicks
  让函数名称编程动词
  例外:当建立类的对象时（classed object）, 函数名称(constructor)要和类（class）的名称向对应 (e.g., lm).
• kConstantName（常量命名法）

语法

每行长度

每行最大长度为80字符。

缩进

当缩进代码的时候，使用两个空格，局部使用tab或者混合使用tab和空格
例外：当在括号内部需要断行的时候，按照括号内首字符对齐。

间隙

所有二进制操作符周围需要间隙 (=, +, -, <-, 等等.).
例外: =如果作为函数的参数传递存在时，周围的空格间隙可有可无.

不要再逗号前加空格，但是总要在其后加空格。

正面实例:

tabPrior <- table(df[df$daysFromOpt < 0, "campaignid"])
total <- sum(x[, 1])
total <- sum(x[1, ])

负面实例:

tabPrior <- table(df[df$daysFromOpt<0, "campaignid"])  # Needs spaces around '<'
tabPrior <- table(df[df$daysFromOpt < 0,"campaignid"])  # Needs a space after the comma
tabPrior<- table(df[df$daysFromOpt < 0, "campaignid"])  # Needs a space before <-
tabPrior<-table(df[df$daysFromOpt < 0, "campaignid"])  # Needs spaces around <-
total <- sum(x[,1])  # Needs a space after the comma
total <- sum(x[ ,1])  # Needs a space after the comma, not before

在左括号之前加空格，除非在函数呼叫内部。

正面实例:
if (debug)

负面实例:
if(debug)

额外的空格间隙 (比如, 每行超过一个的空格) 是允许的，如果可以改善等号和箭头的对齐 (<-).

plot(x    = xCoord,
     y    = dataMat[, makeColName(metric, ptiles[1], "roiOpt")],
     ylim = ylim,
     xlab = "dates",
     ylab = metric,
     main = (paste(metric, " for 3 samples ", sep="")))

不要再括号内部的代码周围或者方括号周围加空格
例外: 总要在逗号后加空格。

正面实例:

if (debug)
x[1, ]

负面实例:

if ( debug )  # debug周围应该没有空格
x[1,]  # 逗号后面需要空格 

花括号

左花括号不能自己一行；右花括号总是自己一行；当花括号内部只 有一行语句的时候，你可以忽略使用花括号；但是，在单行语句的 情况下，你必须保持使用习惯一致，也就是说使用或者不使用花括号。

if (is.null(ylim)) {
  ylim <- c(0, 0.06)
}

xor (but not both)

if (is.null(ylim))
  ylim <- c(0, 0.06)

代码块主体要另起一行。

负面实例:
if (is.null(ylim)) ylim <- c(0, 0.06)
if (is.null(ylim)) {ylim <- c(0, 0.06)}

赋值

赋值使用 <-, 不使用 =.

正面实例:
x <- 5

负面实例:
x = 5

分号

不要使用分号终结一行语句，或者使用分号来在一行放入多个语句（分号在R中并非必须的，可以忽略掉，以保持和其他google样式的一致性）

结构组织

主要布局和顺序

如果每一个人都使用大致相同的顺序，我们就可以轻松快速的读懂每一个人的代码了。

1. 版权声明注释
2. 作者注释
3. 文件描述注释, 包括程序的目的，输入以及输出
4. source() 和 library() 语句
5. 函数定义
6. 可执行语句, (比如., print, plot)

单元测试需要独立成文件保存。命名为 原始文件名_unittest.R.

注释指南

注释代码，注释行需要以 # 和一个空格开始。

短注释需要在代码后加两个空格和一个#，然后加一个空格。

# Create histogram of frequency of campaigns by pct budget spent.
hist(df$pctSpent,
     breaks = "scott",  # method for choosing number of buckets
     main   = "Histogram: fraction budget spent by campaignid",
     xlab   = "Fraction of budget spent",
     ylab   = "Frequency (count of campaignids)")

函数定义和呼叫

函数定义需要首先列出无默认值的参数，然后是有默认值的参数。

不论是函数定义，还是函数呼叫，每行多参数是允许的，但是换行必须在参数赋值之间。
正面实例:

PredictCTR <- function(query, property, numDays,
                       showPlot = TRUE)

负面实例:

PredictCTR <- function(query, property, numDays, showPlot =
                       TRUE)

理想状况下，单元测试一般一样本函数呼叫的形式出现。

函数文档

函数需要包含一个注释，直接在函数定义行的下面。注释需要包 括，一句话的功能描述。函数参数列表。由 Args:指 示, 每一个参数都有有一个描述（包括数据类型）;返回值描述, 由 Returns:指名. 注释必须十分的清楚，这样使用 者可以不用阅读源代码就可以清楚的知道函数的使用方法。

函数使用范例

CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
  # Computes the sample covariance between two vectors.
  #
  # Args:
  #   x: One of two vectors whose sample covariance is to be calculated.
  #   y: The other vector. x and y must have the same length, greater than one,
  #      with no missing values.
  #   verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
  #
  # Returns:
  #   The sample covariance between x and y.
  n <- length(x)
  # Error handling
  if (n <= 1 || n != length(y)) {
    stop("Arguments x and y have invalid lengths: ",
         length(x), " and ", length(y), ".")
  }
  if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
    stop(" Arguments x and y must not have missing values.")
  }
  covariance <- var(x, y)
  if (verbose)
    cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
  return(covariance)
}

TODO 样式

使用一致的样式来撰写TODOs。
TODO(用户名): 明确的行为描述

语言

Attach

由于使用 attach 发生的错误几率很大. 请避免使用。

函数

错误要使用 stop()抛出.

对象和方法

S语言有两个对象系统。S3和S4,在R中都可用。S3有更强的互动性和灵活性。S4更加的正式和严谨. (更多说明参考Thomas Lumley的 "Programmer's Niche: A Simple Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36: http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf.)

使用S3对象和方法可满足一般要求，除非有充足的理由去使用S4。一个主要的理由是S4对象可以直接在C++代码中使用。一个使用S4类和方法的理由是，针对两个参数来分配不同的方法。

避免混用S3和S4方法，S4 方法会忽略 S3 继承，反之亦然。

例外

我们应当尽量遵循上面所描述的编写惯例，除非有更好地理由去改变这一惯例。例外包括，旧系统的代码或者经修改第三方的代码。

临别赠言

使用常识，并保持使用习惯的一致性。

如果你要编辑代码，花几分钟阅读下上下文，熟悉行文的风格。如果其他人习惯在 if 语句周围加空格，你也需要遵循。如果他们的注释有小的星号组成的小盒子，你也要这么做。

使用样式规范的意义在于，大家可以共同参考，从而大家可以吧注意力集中在代码的意义本身，而不是花时间去熟悉别人是如何编写一段代码的。但是本地样式同样十分的重要。如果你写了一段风格迥异的代码，大家在阅读的时候就会失去整体的韵律。所以要尽量避免这样。 好了，这里介绍了足够的编写R代码的规范；代码本身是更有趣的东西。开始享受R的编程之旅吧～～have fun！

参考

http://www.maths.lth.se/help/R/RCC/ - R Coding Conventions
http://ess.r-project.org/ - For emacs users. This runs R in your emacs and has an emacs mode.