标识符命名 Identifiers

• 不要使用连字符( - )，也尽量不使用下划线 ( _ )。
• 变量名：名词或名词性短语，用(.)分隔小写单词，或从第二个单词开始首字母大写（小驼峰法）;
  • 不使用保留字或函数名，如c, list, TRUE, FALSE；
  • 正例: avgClicks, avg.clicks
  • 反例: avg_Clicks, AvgClicks
• 函数名：动词或动词性短语，用(_)分隔小写单词；或小驼峰法（不用大驼峰法）;
  • 不输出(export)到命名空间(NAMESPACE)的函数名前加”.”前缀；
  • 正例: calculateAvgClicks, calculate_avg_clicks
  • 反例: calculate.avg.clicks, CalculateAvgClicks
• S3类(S3 Class)名采用大驼峰法，S4类(S4 Class)名采用大驼峰法并加”S4”前缀
• 方法名(method)也采用函数名相同规则
• 常数命名规则同函数, 但需使用一个k 开头；或全大写：如kConstantName，CONSTANTNAME
• 例外: 当创建一个含类 (class) 属性的对象时, 函数名 (也是constructor) 和类名 (class) 应当匹配 (例如, lm).

空白 Spacing

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

  • 正例:

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

  • 反例:

    tabPrior <- table(df[df$daysFromOpt<0, "campaignid"])   # 在 '<' 两侧需要增加空格
    tabPrior <- table(df[df$daysFromOpt < 0,"campaignid"])  # 逗号后需要一个空格
    tabPrior<- table(df[df$daysFromOpt < 0, "campaignid"])  # 在 <- 前需要一个空格
    tabPrior<-table(df[df$daysFromOpt < 0, "campaignid"])   # 在 <- 两侧需要增加空格
    total <- sum(x[,1])   # 逗号后需要一个空格
    total <- sum(x[ ,1])  # 逗号后需要一个空格, 而非逗号之前
    -2<-1                 # 想想看会发生什么?

• 在前括号前加一个空格, 函数调用时除外。
  • 正例: 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)

    if ( debug )  # debug 的两边不要加空格
    x[1,]         # 需要在逗号后加一个空格 

花括号 Curly Braces

• 前括号永远不应该独占一行；
• 后括号应当总是独占一行。

• 但在处理这类单个语句时， 必须前后一致地要么全部使用花括号，或者全部不用花括号。

  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)
    if (is.null(ylim))              {ylim <- c(0, 0.06)}

总体布局和顺序 General Layout And Ordering

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

• 版权声明注释
• 作者信息注释
• 文件描述注释, 包括程序的用途, 输入和输出
• source() 和 library() 语句
• 函数定义
• 要执行的语句，如果有的话 (例如，print，plot)
• 所有的类定义都写入一个名为allClass.R的独立文件中
• 基本过程/函数定义写入一个名为generic.R的独立文件中
• 单元测试应在另一个名为原始的文件名_unittest.R的独立文件中进行。

编写R加载包的话，请全盘参考William Hadley的指南。

函数文档 Function Documentation

为便于使用roxygen2包将R脚本编译成加载包，强烈建议在函数定义行上方插入一个注释区. 这些注释应当符合roxygen2的语法，每一行都以#’ 开头:

• 此函数的标题，用@title表示（或注释区第一行）;
• 此函数的简要描述和详细描述，用@description（或注释区第三行，第二行留空）和@details表示;
• 此函数的参数列表, 用@param表示, 对每个参数的描述 (包括数据类型);
• 以及对于返回值的描述, 以@return表示;
• 其他可选注释，如@aliases，@author，@examples，@export，@importFrom

这些注释应当描述得足够充分, 这样调用者无须阅读函数中的任何代码即可使用此函数. 而编译后，roxygen2能自动将这些注释生成函数文档(.Rd)。

鼓励用RStudio中书写代码。可使用 Ctrl+Alt+Shift+R 快捷键在函数体上方插入Roxygen2文档骨架。

示例函数 Showcase

#' Computes the sample covariance between two vectors.
#' 
#' \code{CalculateSampleCovariance} computes the sample covariance between two 
#'       vectors.
#' 
#' @details \code{CalculateSampleCovariance} computes the sample covariance 
#'       between two vectors.
#'
#' @param x One of two vectors whose sample covariance is to be calculated.
#' @param y The other vector. x and y must have the same length, greater than one,
#'      with no missing values.
#' @param verbose If TRUE, prints sample covariance; if not, not. Default is TRUE.
#'
#' @return The sample covariance between x and y.
#' @export
#' @import base
#'
#' @examples
#' calculateSampleCovariance(x, y)
#'
#' @author Given Middle Surname, \email{name@@domain.com}
#' @references \url{http://xxxxxxxxxxx}
#' @seealso \code{\link{var}}
#' @keywords covariance
#'