谷歌R语言格式指南


谷歌R语言格式指南

◆ ◆ 

总结:R格式规范


1. 文件名:以.R结束

2. 标识符:variable.name (或 variableName), FunctionName, kConstantName

3. 单行长度限制:至多80个字符

4. 缩进:两个空格,不要使用“tab”

5. 空格

6. 花括号:左花括号在同一行上,右花括号另起一行

7. else:else的前后都是花括号

8. 赋值:使用“<-”,而不是“=”

9. 分号:不要使用

10. 整体布局和顺序

11. 注释准则:所有的注释都应该以#开头并且紧跟一个空格,如果注解与代码在同一行内,那么在#之前需加两个空格

12. 函数的定义和调用

13. 函数文档

14. 函数示例

15. TODO格式:(TODO(用户名))


◆ ◆ 

R语言规则


1. attach:避免使用

2. 函数:用stop()命令引发出错

3. 对象和方法:尽量避免使用S4对象和方法;不要将S3和S4混用

符号与命名


文件名


文件名应该以.R结尾,而且文件的命名应该具有实际意义

好的例子——predict_ad_revenue.R

不好的例子——foo.R


标识符


不要在标识符中使用下划线(_)或者连接符(-)。标识符应该遵照以下约定来命名。变量名的首选形式是全部采用小写字母并且用小数点(.)来区分词(variable.name),但是variableName也是可以接受的;函数名首字母要大写并且不带有小数点(FunctionName);常量和函数名类似,但以k开头。


  • 首选variable.name,variableName也可以接受

好的例子:avg.clicks

可接受的例子: avgClicks

不好的例子: avg_Clicks


  •  函数名 FunctionName

好的例子:CalculateAvgClicks

不好的例子: calculate_avg_clicks , calculateAvgClicks


函数名应该用动词形式表示。


例外:当创建一个类对象,函数名(构造的)和类应该相互匹配(例如:lm)


  • 常量:kConstantName

语法


单行长度


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


缩进


在缩进代码的时候,用两个空格。千万不要用tab或者把tab和空格混合使用。

例外:当圆括号里的内容出现分行的情况时,对准括号里的行首与换行的第一个字符。


空格


在所有二元运算符(=, +, -,<-,等等)的前后都加上一个空格


例外

①调用函数传递参数时,“=”前后的空格可加可不加;

逗号前面不要有空格,但是逗号后面要带一个空格。


好的例子——


谷歌R语言格式指南

不好的例子——


谷歌R语言格式指南


除非是调用函数,其余情况下应该在左圆括号前加上一个空格


好的例子——


if (debug)


不好的例子——


if(debug)


如果加上额外的空格(也就是说在一行中超过一个空格)能够使等号或者箭头看起来更整齐,那也是可以的。


谷歌R语言格式指南


不要在圆括号或者方括号里面的代码前后加上空格


例外

在逗号后面总是要加一个空格


好的例子——


谷歌R语言格式指南


不好的例子——


谷歌R语言格式指南


花括号


左花括号不能单独成行;右花括号一定要单独成行。可以在只有一个语句的代码模块里省略花括号; 但是必须保持对所有的单个语句的代码的一致性。


谷歌R语言格式指南


也可以写成:


谷歌R语言格式指南


一个模块的语句总是另起一行


不好的例子——


谷歌R语言格式指南


else前后的花括号


else语句应该总是在同一行中被花括号围绕着


if (condition) {

  one or more lines

} else {

  one or more lines

}


不好的例子——


谷歌R语言格式指南



不好的例子——


谷歌R语言格式指南



赋值


Use <-, not =, for assignment.

用“<-”来赋值,而不是等号“=”。


好的例子——

x <- 5


坏的例子——

x = 5


分号


不要用分号作为行的结束,或者利用分号在一行中写上多个命令。(分号是不必要的,根据其它Google格式指南的一致性,可以省略)

组织


◆ ◆ 

总体布局和顺序


如果每一个人都使用通用的顺序,那么我们将更快及更容易地阅读和理解其他人的脚本。

1. 版本声明注释

2. 作者信息

3.文件描述注释,包括程序的功能、输入和输出

4.Source() 和 library()声明

5.函数定义

6.执行语句声明,如果适用的话(如:print,plot)

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


◆ ◆ 

注释指南


注释代码——①必需以“#”及一个空格开始注释行;②可以在代码之后加上两个空格,然后以“#”及一个空格开始一个短小的注释。


谷歌R语言格式指南


◆ ◆ 

函数定义和调用


函数定义首先列出不带默认值的参数,随后是带默认值的参数。在函数定义和调用中,一行可以有多个参数;赋值语句之间可以换行。


好的例子——

谷歌R语言格式指南

不好的例子——

谷歌R语言格式指南


理想情况下,单元测试应该作为样本函数调用(共享库路径)。


◆ ◆ 

函数文档


函数应该包含紧接着函数定义行的一个注释部分。这些注释应该包含用一句话完成的函数的描述;函数的参数列表,记作Args以及每个参数的描述(包括数据类型);返回值的描述,记作Returns。注释应该描述得足够清楚,调用者可以不用看函数代码就使用它。


函数示例


谷歌R语言格式指南


  谷歌R语言格式指南


◆ ◆ 

TODO风格


在代码中始终用相同的TODO风格


TODO(username):明确说明要采取的行动


语言


附加


使用attach出现错误的可能性很高。避免使用。


函数


用stop()引发出错


◆ ◆ 

对象和方法


S语言有两个对象系统,S3和S4,它们在R中都是可用的。S3是更加交互式的和灵活的,而S4是更加正式的和严格的。(这两个系统的说明,参考Thomas Lumley的《Programmer’s Niche: A Simple Class, in S3 and S4 in R》


用S3的对象和方法,除非有强烈的理由要使用S4的对象或方法。用S4对象的一个主要理由是在C++代码中直接使用对象。用S4通用/方式的一个主要根据是由两个参数调度。


避免混合使用S3和S4:S4方法忽略S3的继承,反之亦然。


例外——

上面描述的代码约定应该遵循,除非有一个合理的原因使用其它约定。例外包括正常的代码和修改的第三方代码。

原文发布时间为:2016-10-09


本文来自云栖社区合作伙伴“大数据文摘”,了解相关信息可以关注“BigDataDigest”微信公众号


上一篇:web-3g-(163)网易-邮箱-记事本-数据库设计


下一篇:HEVC(H.265)标准的编码器(x265,DivX265)试用