文档章节

R的编码风格指南

openthings
 openthings
发布于 2015/12/16 20:07
字数 2366
阅读 57
收藏 1

概要: R编码风格约定

1. 文件命名: 以.R(大写)结尾

2. 标识符命名: variable.name, FunctionName, kConstantName

3. 单行长度: 不超过80个字符

4. 缩进: 两个空格, 不使用制表符

5. 空白

6. 花括号: 前括号不折行写, 后括号独占一行

7. else语句: 用花括号包围

8. 赋值符号: 使用<-, 而非=

9. 分号: 不要用

10. 总体布局和顺序

11. 注释准则: 所有注释以#开始, 后接一个空格; 行内注释需要在#前加两个空格

12. 函数的定义和调用

13. 函数文档

14. 示例函数

15. TODO书写风格: TODO(用户名)

 

概要: 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, calculateAvgClick

        函数命名应为动词或动词性短语. 

        例外: 当创建一个含类(class)属性的对象时, 函数名(也是constructor)和类名(class)应当匹配(例如, lm).

    kConstantName


语法

    单行长度

        最大单行长度为80个字符. 


缩进

    使用两个空格来缩进代码. 永远不要使用制表符或混合使用二者. 

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

 

空白

    在所有二元操作符(=, +, -, <-等等)的两侧加上空格. 

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

    不可在逗号前加空格, 逗号后总须加空格.

    正例: 

?

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

    反例: 

?

1
2
3
4
5
6
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 ])  # 逗号后需要一个空格, 而非逗号之前

    在前括号前加一个空格, 函数调用时除外. 

    正例:

?

1
if  (debug)

    反例: 

?

1
if (debug)

    多加空格(比如在行内使用多于一个空格)也是可以的, 如果这样做能够改善等号或箭头(<-)的对齐效果. 

?

1
2
3
4
5
6
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 =  "" )))

    不要向圆括号或方括号中的代码两侧加入空格. 

    例外: 逗号后总须加空格. 

    正例:

?

1
2
if  (debug)
x[ 1 , ]

    反例: 

?

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


花括号

    前括号永远不应该独占一行; 后括号应当总是独占一行. 您可以在代码块只含单个语句时省略花括号; 但在处理这类单个语句时, 您必须前后一致地要么全部使用花括号, 或者全部不用花括号. 

?

1
2
3
if  (is. null (ylim)) {
   ylim <- c( 0 0.06 )
}

    或(不可混用)

?

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

    总在新起的一行开始书写代码块的主体. 

    反例: 

?

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

 

用花括号包围else语句

    else语句应该用花括号在同一行包围起来.

    正例:

?

1
2
3
4
5
if  (condition) {
   one or more lines
else  {
   one or more lines
}

    反例:

?

1
2
3
4
5
6
if  (condition) {
   one or more lines
}
else  {
   one or more lines
}

    反例:

?

1
2
3
4
if  (condition)
   one line
else
   one line

 

赋值

    使用<-进行赋值, 不用=赋值. 

    正例: 

?

1
x <-  5

    反例: 

?

1
x =  5


分号

    不要以分号结束一行, 也不要利用分号在同一行放多于一个命令. (分号是毫无必要的, 并且为了与其他Google编码风格指南保持一致, 此处同样略去. )

 

代码组织

    总体布局和顺序

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

            1. 版权声明注释

            2. 作者信息注释

            3. 文件描述注释, 包括程序的用途, 输入和输出

            4. source()和library()语句

            5. 函数定义 

            6. 要执行的语句, 如果有的话(例如, print, plot)

        单元测试应在另一个名为原始的文件名_unittest.R的独立文件中进行. 

 

    注释准则

        注释您的代码. 整行注释应以#后接一个空格开始.

        行内短注释应在代码后接两个空格, #, 再接一个空格. 

?

1
2
3
4
5
6
# 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)" )

 

    函数的定义和调用

        函数定义应首先列出无默认值的参数, 然后再列出有默认值的参数. 

        函数定义和函数调用中, 允许每行写多个参数; 折行只允许在赋值语句外进行. 

        正例: 

?

1
PredictCTR <- function(query, property, numDays, showPlot = TRUE)

        反例: 

?

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

        理想情况下, 单元测试应该充当函数调用的样例(对于包中的程序来说). 


 

    函数文档

        函 数在定义行下方都应当紧接一个注释区. 这些注释应当由如下内容组成: 此函数的一句话描述; 此函数的参数列表, 用Args: 表示, 对每个参数的 描述(包括数据类型); 以及对于返回值的描述, 以Returns: 表示. 这些注释应当描述得足够充分, 这样调用者无须阅读函数中的任何代码即可 使用此函数. 

 

    示例函数

?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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书写风格

        编码时通篇使用一种一致的风格来书写TODO. 

        TODO(用户名): 所要采取行动的明确描述

 

语言 

    Attach

        使用attach造成错误的可能数不胜数. 避免使用它. 

 

    函数

        错误(error)应当使用stop()抛出. 

 

    对象和方法

        S 语言中有两套面向对象系统, S3和S4, 在R中这两套均可使用. S3方法的可交互性更强, 更加灵活, 反之, S4方法更加正式和严格. (对这 两套系统的说明, 参见ThomasLumley的文 章"Programmer'sNiche: ASimpleClass, inS3andS4", 发表于RNews4/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并且提供了一个emacsmode.


本文转载自:http://my.oschina.net/u/1791586/blog/279573

openthings
粉丝 324
博文 1140
码字总数 689435
作品 1
东城
架构师
私信 提问
free-programming-books-zh.md

语言无关MySQL NoSQL PostgreSQL Web WEB服务器 其它 函数式概念 分布式系统 在线教育 大数据 操作系统 数据库 智能系统 正则表达式 版本控制 程序员杂谈 管理和监控 编程艺术 编译原理 编辑...

银月光海
2016/05/20
124
0
总有你要的编程书单(GitHub )

目录 IDE IntelliJ IDEA 简体中文专题教程 MySQL 21分钟MySQL入门教程 MySQL索引背后的数据结构及算法原理 NoSQL Disque 使用教程 Neo4j .rb 中文資源 Redis 命令参考 Redis 设计与实现 The ...

汇智网
2017/11/22
0
0
Fanta/free-programming-books-zh_CN

免费的编程中文书籍索引 免费的编程中文书籍索引,欢迎投稿。 国外程序员在 stackoverflow 推荐的程序员必读书籍,中文版。 stackoverflow 上的程序员应该阅读的非编程类书籍有哪些? 中文版...

Fanta
2016/11/14
0
0
免费的编程中文书籍索引【收藏速度】

语言无关类 优质博客 PyTab在线手册中心 ImportNew 廖雪峰的官方网站 程序员博客墙 操作系统 开源世界旅行手册 鸟哥的Linux私房菜 Linux 系统高级编程 The Linux Command Line (中英文版) L...

yonghu86
2015/04/15
0
0
开源电子书

目录 语言无关类 操作系统 智能系统 分布式系统 编译原理 函数式概念 计算机图形学 WEB服务器 版本控制 编辑器 NoSQL PostgreSQL MySQL 管理和监控 项目相关 设计模式 Web 大数据 编程艺术 ...

zting科技
2017/12/11
0
0

没有更多内容

加载失败,请刷新页面

加载更多

JVM -- Java堆结构及对象分代

Hello,今天记录下 Java虚拟机中的其中一个重点知识 --> Java堆。 一起学习,一起进步。继续沉淀,慢慢强大。希望这文章对您有帮助。若有写的不好的地方,欢迎评论给建议哈! 初写博客不久,...

猫狗熊
20分钟前
3
0
elastic-job的使用

概述: 公司用了elastic-job来执行定时任务和管理定时任务,所以最近研究了一下写了个demo,由于我是把zookeeper部署在了docker上的,所以这里简单介绍下docke的基础命令。 1、Docker基础命令...

你个小机灵鬼
21分钟前
3
0
Cadence Allegro 中skill应用教程:让代码替我们打工

SKILL语言是Candence提供给用户的一个开发接口,利用其本身提供的接口函数和SKILL语言完成自动化操作的功能。 怎么查看SKILL: 1.可以直接用写字板打开进行编辑或看功能说明。 2.想自己写或改...

demyar
22分钟前
3
0
如何看待技术债务

关于技术债务,做开发的同学对如下场景应该不陌生: 为了敢项目进度,详细设计、单元测试等过程就不写了,以后补 需求变化万千,原本架构设计无法满足新的需求,可是又不想动架构,于是绕过架...

嘿嘿嘿IT
24分钟前
3
0
深入理解 web 协议(一)- http 包体传输

本文首发于 vivo互联网技术 微信公众号 链接:https://mp.weixin.qq.com/s/WlT8070LlrnSODFRDwZsUQ 作者:吴越 开坑这个系列的原因,主要是在大前端学习的过程中遇到了不少跟web协议有关的问...

vivo互联网技术
24分钟前
3
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部