来自 Google 的 R 语言编码气势气魄指南
R 语言是一门主要用于统计计较和画图的高级编程语言. 这份 R 语言编码气势气魄指南旨在让我们的 R 代码更容易阅读、分享和查抄. 以下法则系与 Google 的 R 用户群体协同设计而成.
文件名应以 .R (大写) 末了, 文件名自己要有意义.
正例: predict_ad_revenue.R
反例: foo.R
在标识符中不要利用下划线 ( _ ) 或连字符 ( – ). 标识符应按照如下老例定名. 变量名应利用点 (.) 脱离所有的小写字母或单词; 函数名首字母大写, 不消点脱离 (所含单词首字母大写); 常数定名法则同函数, 但需利用一个 k 开头.
正例: avg.clicks
反例: avg_Clicks , avgClicks
正例: CalculateAvgClicks
反例: calculate_avg_clicks , calculateAvgClicks
函数定名应为动词或动词性短语.
破例: 当建设一个含类 (class) 属性的工具时, 函数名 (也是constructor) 和类名 (class) 该当匹配 (譬喻, lm).
较大单行长度为 80 个字符.
利用两个空格来缩进代码. 永远不要利用制表符或殽杂利用二者.
破例: 当括号内产生折行时, 所折行与括号内的第一个字符对齐.
在所有二元操纵符 (=, +, -, <-, 等等) 的两侧加上空格.
破例: 在函数挪用中通报参数时 = 双方的空格可加可不加.
不行在逗号前加空格, 逗号后总须加空格.
正例:
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]) # 逗号后需要一个空格, 而非逗号之前
在前括号前加一个空格, 函数挪用时除外.
正例:
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)}或 (不行混用)
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
不要以分号竣事一行, 也不要操作分号在同一行放多于一个呼吁. (分号是毫无须要的, 而且为了与其他Google编码气势气魄指南保持一致, 此处同样略去.)
假如所有人都以沟通顺序布置代码内容, 我们就可以越发轻松快速地阅读并领略他人的剧本了.
单位测试应在另一个名为 原始的文件名_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.
TODO(您的用户名): 所要采纳动作的明晰描写
利用 attach 造成错误的大概数不胜数. 制止利用它.
错误 (error) 该当利用 stop() 抛出.
S 语言中有两套面向工具系统, S3 和 S4, 在 R 中这两套均可利用. S3 要领的可交互性更强, 越发机动, 反之,
S4 要领越发正式和严格. (对这两套系统的说明, 拜见 Thomas Lumley 的文章 “Programmer’s Niche: A
Simple Class, in S3 and S4”, 颁发于 R News 4/1, 2004, 33 – 36 页: http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf.)
这里推荐利用 S3 工具和要领, 除非您有很强烈的来由去利用 S4 工具和要领. 利用 S4 工具的一个主要来由是在 C++ 代码中直接利用工具. 利用一个 S4 泛型/要领的主要来由是对双参数的分发.
制止混用 S3 和 S4: S4 要了解忽略 S3 中的担任, 反之亦然.
除非有不去这样做的好来由, 不然该当遵循以上描写的编码老例. 破例包罗遗留代码的维护和对第三方代码的修改.
遵守知识, 前后一致.假如您在编辑现有代码, 花几分钟看看代码的上下文并弄清它的气势气魄. 假如其他人在 if 语句周围利用了空格, 那您也应该这样做. 假如他们的注释是用星号构成的小盒子围起来的, 那您也要这样写。
遵循编码气势气魄准则的意义在于, 人们相当于有了一个编程的通用词汇表, 于是人们可以专注于您在 说什么, 而不是您是 怎么说
的. 我们在这里提供全局的编码气势气魄法则以便人们相识这些词汇, 但局部气势气魄也很重要. 假如您插手文件中的代码看起来和周围的已有代码截然差异,
那么代码阅读者的阅读节拍就会被粉碎. 只管制止这样做. OK, 关于如何写代码已经写得够多了; 代码自己要有趣的多. 编码愉快!
http://www.maths.lth.se/help/R/RCC/ – R语言编码老例
http://ess.r-project.org/ – 为 emacs 用户而生. 在您的 emacs 中运行 R 而且提供了一个 emacs mode.