R语言观察日志(part16)--Google‘s R Style Guide

学习笔记，仅供参考

自翻，有错必究

文章目录

Google's R Style Guide
- summary
- - R语言风格
  - R语言规则
- 符号和命名
- - 文件名
  - 标识符
  - 每行长度(注意)
  - 缩进
  - 空格
  - 花括号
  - 被大括号括起来
  - 赋值
  - 分号
  - 总体布局和排序
  - 注释
  - 函数定义和调用
  - 功能文档
  - 例子函数
  - TODO Style(to do 要做, 但是没有完成的事)
  - 附加
  - 功能
  - 对象和方法
  - 特别的
- 临别赠言
- 参考文献

Google’s R Style Guide

R是一种高级编程语言，主要用于统计计算和图形，R编程风格指南的目标是使我们的R代码更容易阅读、共享和验证，以下规则是与谷歌的整个R用户社区合作设计的。

summary

R语言风格

条目	风格
文件名	以`.R`结尾
标识符	`variable.name`(或variableName)，FunctionName，kConstantName
每行长度	最多80个字符
缩进	两个空格，没有制表符
空格
花括号	左花括号在同一行，右花括号自占一行
else	用括号将else括起来
赋值	使用 `<-`，而不是 `=`
分号	不要使用它们
总体布局和排序
注释	所有注释以`#`开头，后跟空格；`#`之前的内嵌注释需要两个空格
函数定义和调用
功能文档
示例函数
任何风格	`TODO(username)`

R语言规则

条目	规则
附加(Attach)	避免使用`it`
函数	应该使用`stop()`引发错误
对象和方法	尽可能避免S4对象和方法；永远不要混淆S3和S4

符号和命名

文件名

文件名必须有意义，且以.R结尾。

good例子：predict_ad_revenue.R

bad例子：foo.R

标识符

标识符中不要使用下划线(_)或连字符(-)，标识符应根据以下约定命名：

变量名的首选形式是所有小写字母和用点分隔的单词(variable.name)，但variableName也是可以接受的；
函数名以大写字母开头，没有点(FunctionName);
常数的命名类似于函数，但以k开头。

variable.name是首选，variableName也是可以接受的：

good例子：avg.clicks

ok例子：avgClicks

bad例子：avg_Clicks

FunctionName：

good例子：CalculateAvgClicks

bad例子：calculate_avg_clicks，calculateAvgClicks

使函数名成为动词。

特别的：当创建一个classed object时，函数名(构造函数)和类应该匹配(例如，lm)

每行长度(注意)

每行最大字符数为80个字符。

缩进

缩进代码时，请使用两个空格。

切勿使用制表符或制表符和空格的混合。

特别的：当括号内出现换行符时，将换行与括号内的第一个字符对齐。

空格

在所有二元运算(=, +, -, <-等)符周围放置空格

特别的：在函数调用中传递参数时，=周围的空格是可选的。

不要在逗号前加空格，但一定要在逗号后加空格。

good例子：

tab.prior <- table(df[df$days.from.opt < 0, "campaign.id"])
total <- sum(x[, 1])
total <- sum(x[1, ])

bad例子：

tab.prior <- table(df[df$days.from.opt<0, "campaign.id"])
# < 周围需要空格
tab.prior <- table(df[df$days.from.opt < 0,"campaign.id"])
# 逗号后需要一个空格
tab.prior<- table(df[df$days.from.opt < 0, "campaign.id"])
# <- 前需要一个空格
tab.prior<-table(df[df$days.from.opt < 0, "campaign.id"])
# <- 周围需要空格
total <- sum(x[,1])
# 逗号后需要一个空格
total <- sum(x[ ,1])
# 逗号后面需要空格，而不是前面

在左括号前加一个空格，函数调用除外。

good例子：if (debug)

bad例子：if(debug)

如果存在额外的空格(即一行中有多个空格)可以增加等号或箭头(<-)的对齐效果，那也没关系：

plot(x    = x.coord,y    = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],ylim = ylim,xlab = "dates",ylab = metric,main = (paste(metric, " for 3 samples ", sep = "")))

不要在括号或方括号内的代码周围放置空格。

特别的：逗号后面一定要有空格。

good例子：

if (debug)
x[1, ]

bad例子：

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

花括号

左花括号不应该单独成一行，右花括号应该总是单独成一行；

当一个块由一条语句组成时，可以省略花括号；

但是，对于单个语句块，必须始终使用或不使用花括号。

good例子：

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

或者：

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

bad例子：

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

被大括号括起来

else语句应该总是在同一行用花括号括起来。

good例子：

if (condition) {one or more lines
} else {one or more lines
}

bad例子：

if (condition) {one or more lines
}
else {one or more lines
}

bad例子：

if (condition)one line
elseone line

赋值

使用 <-，而不是 =进行赋值。

good例子：x <- 5

bad例子：x = 5

分号

不要用分号结束您的行，也不要用分号将多个命令放在同一行。(分号不是必须的，为了与其他Google样式指南保持一致，省略分号。)

总体布局和排序

如果每个人都使用相同的顺序，我们将能够更快、更容易地阅读和理解彼此的脚本。

词序	内容
1	版权声明注释
2	作者的话
3	文件描述注释，包括程序的目的、输入和输出
4	`source()`和`library()`语句
5	定义功能
6	已执行的语句(如打印、绘图)

单元测试应该放在一个单独的名为originalfilename_test.R的文件中

注释

注释你的代码，整个注释行应以#和一个空格开始。

短注释可以放在代码后面，前面有两个空格，#，然后是一个空格。

good例子：

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

函数定义和调用

函数定义应该首先列出不带默认值的参数，然后列出带默认值的参数；

在函数定义和函数调用中，每行允许多个参数；

只允许在赋值(assignments)之间换行(读不懂就看下面的例子)。

good例子：

PredictCTR <- function(query, property, num.days,show.plot = TRUE)

bad例子：

PredictCTR <- function(query, property, num.days, show.plot =TRUE)

理想情况下，单元测试应该作为示例函数调用(用于shared library routines)。

功能文档

函数应该在函数定义行的正下方包含一个注释部分；

这些注释应该包含对功能的一句话描述；

函数参数的列表，用Args:表示，并对每个参数进行描述(包括数据类型)；

返回值的描述，用Returns:表示。

注释应该具有足够的描述性，以便调用方可以使用该函数，而无需阅读函数的任何代码。

例子函数

good例子：

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 handlingif (n <= 1 || n != length(y)) {stop("Arguments x and y have different 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 Style(to do 要做, 但是没有完成的事)

在你的代码中使用一致的todo风格。

good例子：

TODO(username): Explicit description of action to be taken

附加

使用attach时产生错误的可能性很大，请避免它。

功能

应该使用stop()抛出错误(Errors)。

对象和方法

S语言有两个对象系统，S3和S4，这两个系统都可以在r中使用。S3方法更具交互性和灵活性，而S4方法则更加正式和严格。

使用S3对象和方法，除非有充分的理由使用S4对象或方法。

使用S4对象的充分理由是：

S4对象可以直接在c++代码中使用对象；(an S4 object would be to use objects directly in C++ code)
S4泛型/方法将在两个参数上进行分派。(an S4 generic/method would be to dispatch on two arguments.)

避免混合S3和S4: S4方法忽略S3继承，反之亦然。(Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and vice-versa)

特别的

应该遵循上面描述的编码约定，除非有充分的理由不这样做。例外情况包括遗留代码和修改第三方代码。

临别赠言

运用常识，保持一致。

如果您正在编辑代码，请花几分钟时间查看您周围的代码并确定其风格。

如果别人在if子句周围使用空格，你也应该这样做。如果他们的评论周围有星星的小框，那么让你的评论周围也有星星的小框。

制定风格指南的要点是要有一个通用的编码词汇表，这样人们就可以专注于你所说的内容，而不是你是如何说的。

我们在这里提供全局样式规则，以便人们了解编码词汇表。但地方风格也很重要。如果添加到文件中的代码看起来与周围现有的代码有很大的不同，不连续会让读者在阅读时失去节奏。尽量避免这种情况。

关于写代码的内容讲得够多了，代码本身要有趣得多。玩得开心！

参考文献

R编码约定：ht#tps://#pa#n.ba#id#u.com/s#/16McHYOBI_P-dqOrB7VosUg

emacs用户，它在emacs中运行，并具有emacs模式：