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语言规则

符号和命名

文件名

文件名必须有意义，且以​​.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
else
  one line

赋值

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

good例子：​​x <- 5​​

bad例子：​​x = 5​​

分号

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

总体布局和排序

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

单元测试应该放在一个单独的名为​​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 buckets
     main   = "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 handling
  if (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模式：​​