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

本文转自Xiao Nan的博客

R语言是一门主要用于统计计算和绘图的高级编程语言. 这份 R 语言编码风格指南旨在让我们的 R 代码更容易阅读、分享和检查. 以下规则系与 Google 的 R 用户群体协同设计而成.

  • 概要: R编码风格约定
  • 概要: R语言使用规则
    1. attach: 避免使用
    2. 函数: 错误 (error) 应当使用 stop() 抛出
    3. 对象和方法: 尽可能避免使用 S4 对象和方法; 永远不要混用 S3 和 S4
  • 表示和命名
  • 文件命名
      文件名应以

.R

      (大写) 结尾, 文件名本身要有意义.
      正例:

predict_ad_revenue.R

      反例:

foo.R

  • 标识符命名
      在标识符中不要使用下划线 (

_

      ) 或连字符 (

-

      ). 标识符应根据如下惯例命名. 变量名应使用点 (

.

      ) 分隔所有的小写字母或单词; 函数名首字母大写, 不用点分隔 (所含单词首字母大写); 常数命名规则同函数, 但需使用一个

k

      开头.
    • variable.name  正例: avg.clicks 反例: avg_Clicks , avgClicks
    • FunctionName  正例: CalculateAvgClicks 反例: calculate_avg_clicks , calculateAvgClicks 函数命名应为动词或动词性短语. 例外: 当创建一个含类 (class) 属性的对象时, 函数名 (也是constructor) 和类名 (class) 应当匹配 (例如, lm).
    • kConstantName
  • 语法
  • 单行长度
      最大单行长度为 80 个字符.
  • 缩进
      使用两个空格来缩进代码. 永远不要使用制表符或混合使用二者.

例外: 当括号内发生折行时, 所折行与括号内的第一个字符对齐.

  • 空白
      在所有二元操作符 (

=

      ,

+

      ,

-

      ,

<-

      , 等等) 的两侧加上空格.

例外: 在函数调用中传递参数时 = 两边的空格可加可不加.

      不可在逗号前加空格, 逗号后总须加空格.
      正例:
tabPrior <- table(df[df$daysFromOpt < 0, "campaignid"]) total <- sum(x[, 1]) total <- sum(x[1, ])
      反例:
tabPrior <- table(df[df$daysFromOpt<0, "campaignid"])  # Needs spaces around ‘<‘
tabPrior <- table(df[df$daysFromOpt < 0,"campaignid"])  # Needs a space after the comma
tabPrior<- table(df[df$daysFromOpt < 0, "campaignid"])  # Needs a space before <-
tabPrior<-table(df[df$daysFromOpt < 0, "campaignid"])  # Needs spaces around <-
total <- sum(x[,1])  # Needs a space after the comma
total <- sum(x[ ,1])  # Needs a space after the comma, not before
      在前括号前加一个空格, 函数调用时除外.
      正例:

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编码风格指南保持一致, 此处同样略去.)
  • 代码组织
  • 总体布局和顺序
      如果所有人都以相同顺序安排代码内容, 我们就可以更加轻松快速地阅读并理解他人的脚本了.
      1. 版权声明注释
      2. 作者信息注释
      3. 文件描述注释, 包括程序的用途, 输入和输出
      4. source() 和 library() 语句
      5. 函数定义
      6. 要执行的语句, 如果有的话 (例如, 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)
      反例:
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(您的用户名): 所要采取行动的明确描述

  • 语言
  • Attach
      使用

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.

时间： 2024-10-05 09:43:36

来自 Google 的 R 语言编码风格指南的相关文章

R 语言编码风格指南

R 语言是一门主要用于统计计算和绘图的高级编程语言.这份 R 语言编码风格指南旨在让我们的 R代码更容易阅读.分享和检查.以下规则系与 Google 的 R 用户群体协同设计而成. 概要: R编码风格约定 文件命名: 以 .R (大写) 结尾 标识符命名: variable.name, FunctionName, kConstantName 单行长度: 不超过 80 个字符 缩进: 两个空格, 不使用制表符 空白 花括号: 前括号不折行写, 后括号独占一行 赋值符号: 使用 <-, 而非 = 分

(转)PEP 8——Python编码风格指南

PEP 8--Python编码风格指南标签(空格分隔): Python PEP8 编码规范原文:https://lizhe2004.gitbooks.io/code-style-guideline-cn/content/python/python-pep8.html https://python.freelycode.com/contribution/detail/47------PEP8中文版 -- Python编码风格指南(上,中,下) https://python.freelycode.c

JavaScript 编码风格指南

A.1  缩进 // 4个空格的层级缩进 if (true) { doSomething(); } A.2  行的长度 // 每行限于80个字符,超出则在运算符后换行,缩进2个层级(8个空格) doSomething(argument1, argument2, argument3, argument4, argument5); A.3  原始值 // 字符串使用双引号及长字符串的链接 var name = "Nicholas", longStr = "this is a lo

【翻译】Ext JS——高效的编码风格指南

原文:ExtJS - Efficient coding style guide 作者:Raja 切勿使用"new"关键字:在Ext JS中,使用"new"关键字来创建一个组件或类的实例是一种错误的做法,因为这没有遵循组件的生命周期.应该使用Ext.create方法来创建对象,例如: 错误: var obj = new Ext.panel.Panel(); 正确: var obj = Ext.create('Ext.panel.Panel'); 初始化直接量:不要直接

【翻译】EXTJS 编码风格指南与实例

原文:EXTJS Code Style Guide with examples Ext JS风格指南: 熟知的且易于学习 快速开发,易于调试,轻松部署 组织良好.可扩展和可维护 Ext JS应用程序的命名约定: 1.类 类名应使用驼峰命名(CamelCased).不要使用下划线,或其他连接字符.如:MyCustomClass 不是通过Sencha分发的类,永远不要使用Ext作为顶层命名空间.在类名中,应至少使用一次点号来划分命名空间.如TopLevelNamespace.MyClassName

JavaScript编码风格指南(中文版)

前言:程序语言的编码风格对于一个长期维护的软件非常重要,特别是在团队协作中.如果一个团队使用统一规范的编码分风格,可以提高团队的协作水平和工作效率.编程风格指南的核心是基本的格式化规则,这些规则决定了如何编写高水准的代码.本指南来自于<编写可维护的JavaScript>这本书,基于"Java语言编码规范"和Crockford的JavaScript编程规范,还有Nicbolas的一些个人经验和喜好.写作本文旨在加深自己印象,也为了更多人的了解到JS编码风格,提高自己的编码质量

PHP编码风格指南 (PHP-FIG PSR-2)

本指南是 PSR-1 基本编码标准 的扩展. 本指罗列了通用的PHP代码格式规则和建议,意在减少不同作者的编码风格差异带来的认知障碍. 这里的风格约定衍生自若干成员项目.指南作者们在多个项目中协作,推动了这些指导条款落地. 指南的关键在于共享,而不是规则本身. 文中涉及的关键词 "MUST 必须", "MUST NOT 必须不", "REQUIRED 必需", "SHALL 会", "SHALL NOT 不会&quo

[CoffeeScript]编码风格指南

?? 这份指南阐述了一些 CoffeeScript 的最佳实践和编码惯例. 这份指南是社群驱动的,非常鼓励大家来贡献内容. 请注意这还是一份正在完善的指南:仍有很多地方可以改进,有些已制定的准则也不一定是社区惯用的(基于此,在适当的情况下,这些有待斟酌的准则将有可能被修改或删除.) 灵感 本指南中的很多细节受到了几份现有的风格指南和其他资源的启发.特别是: PEP-8: Style Guide for Python Code Bozhidar Batsov's Ruby Style Guide

《编写可维护的 Javascript》读书笔记（附录 A 部分）：Javascript 编码风格指南（1）原始值

记录一下比较有用的编码规范(该指南是基于 Java 语言编码规范和 Javascript 编程规范,同时结合作者 Nicholos Zakas 的个人经验和喜好). 一些关于格式(包括缩进.行的长度.运算符间距.括号间距.对象直接量.注释.单行注释.多行注释等类似的规范)的规范这里不做记录. A.3 原始值 // 好的写法 var name = "Nicholos"; // 不好的写法:单引号 var name = 'Nicholos'; // 不好的写法:字符串结束之前换行 var