R语言代码规范

Jeason

1761字约6分钟

2018-11-05

R语言是一门主要用于统计计算和绘图的高级编程语言. 在使用R时，好的代码编写和注释规范，可以提高代码的可读性和工作效率. 然而，什么样的规范更有利于我们自己使用和第三方解读？在此，建议使用《来自Google的R语言编码风格指南》一文中推荐的代码写作风格，这个规则是由Google的R用户群体协同设计而成.

概要: R编码风格约定

文件命名: 以 .R (大写) 结尾
标识符命名: variable.name, FunctionName, kConstantName
单行长度: 不超过80个字符
缩进: 两个空格, 不使用制表符
空白
花括号: 前括号不折行写, 后括号独占一行
赋值符号: 使用 <-, 而非 =
分号: 不要用
总体布局和顺序
注释准则: 所有注释以 # 开始, 后接一个空格; 行内注释需要在 # 前加两个空格
函数的定义和调用
函数文档
示例函数
TODO书写风格: TODO(您的用户名)

1. 表示和命名

文件命名

文件名应以 .R (大写) 结尾, 文件名本身要有意义. 如: predict_ad_revenue.R

标识符命名

在标识符中不要使用下划线 ( _ ) 或连字符 ( - ). 标识符应根据如下惯例命名. 变量名应使用点 (.) 分隔所有的小写字母或单词; 函数名首字母大写, 不用点分隔 (所含单词首字母大写); 常数命名规则同函数, 但需使用一个 k 开头.

变量命名正例: avg.clicks 反例: avg_Clicks , avgClicks
FunctionName 正例: CalculateAvgClicks 反例: calculate_avg_clicks , calculateAvgClicks 函数命名应为动词或动词性短语.

例外: 当创建一个含类 (class) 属性的对象时, 函数名 (也是constructor) 和类名 (class) 应当匹配 (例如, lm).

kConstantName

2. 语法

单行长度

最大单行长度为 80 个字符.

缩进

使用两个空格来缩进代码. 永远不要使用制表符或混合使用二者. 例外: 当括号内发生折行时, 所折行与括号内的第一个字符对齐.

空白

在所有二元操作符 (=, +, -, <-, 等等) 的两侧加上空格. 例外: 在函数调用中传递参数时 = 两边的空格可加可不加.

不可在逗号前加空格, 逗号后总须加空格.

例如:

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

在前括号前加一个空格, 函数调用时除外. 例如：

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 )  # debug 的两边不要加空格
x[1,]  # 需要在逗号后加一个空格

花括号

前括号永远不应该独占一行; 后括号应当总是独占一行. 您可以在代码块只含单个语句时省略花括号; 但在处理这类单个语句时, 您必须前后一致地要么全部使用花括号, 或者全部不用花括号.

例如：

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

或者：

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

总在新起的一行开始书写代码块的主体。

赋值

使用 <- 进行赋值, 不用 = 赋值

分号

不要以分号结束一行, 也不要利用分号在同一行放多于一个命令. (分号是毫无必要的, 并且为了与其他Google编码风格指南保持一致, 此处同样略去.)

3. 代码组织

总体布局和顺序

如果所有人都以相同顺序安排代码内容, 我们就可以更加轻松快速地阅读并理解他人的脚本了.

版权声明注释
作者信息注释
文件描述注释, 包括程序的用途, 输入和输出
source() 和 library() 语句
函数定义
要执行的语句, 如果有的话 (例如, 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)

理想情况下, 单元测试应该充当函数调用的样例 (对于包中的程序来说).

函数文档

函数在定义行下方都应当紧接一个注释区. 这些注释应当由如下内容组成: 此函数的一句话描述; 此函数的参数列表, 用 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书写风格

编码时通篇使用一种一致的风格来书写TODO. TODO(您的用户名): 所要采取行动的明确描述

Reference：

来自Google的R语言编码风格指南