Google编程规范.docx
《Google编程规范.docx》由会员分享，可在线阅读，更多相关《Google编程规范.docx（9页珍藏版）》请在冰豆网上搜索。
Google编程规范
GoogleJava编程风格指南
January20,2014
作者：
Hawstein
出处：
posts/
声明：
本文采用以下协议进行授权：
自由转载-非商用-非衍生-保持署名|CreativeCommonsBY-NC-ND，转载请注明作者及出处。
1.前言
2.源文件基础
3.源文件结构
4.格式
5.命名约定
6.编程实践
7.Javadoc
8.后记
前言
这份文档是GoogleJava编程风格规范的完整定义。
当且仅当一个Java源文件符合此文档中的规则，我们才认为它符合Google的Java编程风格。
与其它的编程风格指南一样，这里所讨论的不仅仅是编码格式美不美观的问题，同时也讨论一些约定及编码标准。
然而，这份文档主要侧重于我们所普遍遵循的规则，对于那些不是明确强制要求的，我们尽量避免提供意见。
术语说明
在本文档中，除非另有说明：
1.术语class可表示一个普通类，枚举类，接口或是annotation类型（@interface）
2.术语comment只用来指代实现的注释（implementationcomments），我们不使用“documentationcomments”一词，而是用Javadoc。
其他的术语说明会偶尔在后面的文档出现。
指南说明
本文档中的示例代码并不作为规范。
也就是说，虽然示例代码是遵循Google编程风格，但并不意味着这是展现这些代码的唯一方式。
示例中的格式选择不应该被强制定为规则。
源文件基础
文件名
源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java。
文件编码：
UTF-8
源文件编码格式为UTF-8。
特殊字符
空白字符
除了行结束符序列，ASCII水平空格字符（0x20，即空格）是源文件中唯一允许出现的空白字符，这意味着：
1.所有其它字符串中的空白字符都要进行转义。
2.制表符不用于缩进。
特殊转义序列
对于具有特殊转义序列的任何字符（\b,\t,\n,\f,\r,\“,\‘及\），我们使用它的转义序列，而不是相应的八进制（比如\012）或Unicode（比如\u000a）转义。
非ASCII字符
对于剩余的非ASCII字符，是使用实际的Unicode字符（比如∞），还是使用等价的Unicode转义符（比如\u221e），取决于哪个能让代码更易于阅读和理解。
Tip:
在使用Unicode转义符或是一些实际的Unicode字符时，建议做些注释给出解释，这有助于别人阅读和理解。
例如：
StringunitAbbrev="μs";|赞，即使没有注释也非常清晰
StringunitAbbrev="\u03bcs";;
不要换行
import语句不换行，列限制节）并不适用于import语句。
（每个import语句独立成行）
顺序和间距
import语句可分为以下几组，按照这个顺序，每组由一个空行分隔：
1.所有的静态导入独立成组
2.imports（仅当这个源文件是在包下）
3.第三方的包。
每个顶级包为一组，字典序。
例如：
android,com,junit,org,sun
4.javaimports
5.javaximports
组内不空行，按字典序排列。
类声明
只有一个顶级类声明
每个顶级类都在一个与它同名的源文件中（当然，还包含.java后缀）。
例外：
，该文件中可没有package-info类。
类成员顺序
类的成员顺序对易学性有很大的影响，但这也不存在唯一的通用法则。
不同的类对成员的排序可能是不同的。
最重要的一点，每个类应该以某种逻辑去排序它的成员，维护者应该要能解释这种排序逻辑。
比如，新的方法不能总是习惯性地添加到类的结尾，因为这样就是按时间顺序而非某种逻辑来排序的。
重载：
永不分离
当一个类有多个构造函数，或是多个同名方法，这些函数/方法应该按顺序出现在一起，中间不要放进其它函数/方法。
格式
术语说明：
块状结构（block-likeconstruct）指的是一个类，方法或构造函数的主体。
需要注意的是，数组初始化中的初始值可被选择性地视为块状结构节）。
大括号
使用大括号（即使是可选的）
大括号与if,else,for,do,while语句一起使用，即使只有一条语句（或是空），也应该把大括号写上。
非空块：
K&R风格
对于非空块和块状结构，大括号遵循Kernighan和Ritchie风格（Egyptianbrackets）:
左大括号前不换行
左大括号后换行
右大括号前换行
如果右大括号是一个语句、函数体或类的终止，则右大括号后换行;否则不换行。
例如，如果右大括号后面是else或逗号，则不换行。
示例：
returnnewMyClass（）{
@Overridepublicvoidmethod（）{
if（condition（））{
try{
something（）;
}catch（ProblemExceptione）{
recover（）;
}
}
}
};
节给出了enum类的一些例外。
空块：
可以用简洁版本
一个空的块状结构里什么也不包含，大括号可以简洁地写成{}，不需要换行。
例外：
如果它是一个多块语句的一部分（if/else或try/catch/finally），即使大括号内没内容，右大括号也要换行。
示例：
voiddoNothing（）{}
块缩进：
2个空格
每当开始一个新的块，缩进增加2个空格，当块结束时，缩进返回先前的缩进级别。
缩进级别适用于代码和注释。
（见节中的代码示例）
一行一个语句
每个语句后要换行。
列限制：
80或100
一个项目可以选择一行80个字符或100个字符的列限制，除了下述例外，任何一行如果超过这个字符数限制，必须自动换行。
例外：
1.不可能满足列限制的行（例如，Javadoc中的一个长URL，或是一个长的JSNI方法参考）。
2.package和import语句（见节和节）。
3.注释中那些可能被剪切并粘贴到shell中的命令行。
自动换行
术语说明：
一般情况下，一行长代码为了避免超出列限制（80或100个字符）而被分为多行，我们称之为自动换行（line-wrapping）。
我们并没有全面，确定性的准则来决定在每一种情况下如何自动换行。
很多时候，对于同一段代码会有好几种有效的自动换行方式。
Tip:
提取方法或局部变量可以在不换行的情况下解决代码过长的问题（是合理缩短命名长度吧）
从哪里断开
自动换行的基本准则是：
更倾向于在更高的语法级别处断开。
1.如果在非赋值运算符处断开，那么在该符号前断开（比如+，它将位于下一行）。
注意：
这一点与Google其它语言的编程风格不同（如C++和JavaScript）。
这条规则也适用于以下“类运算符”符号：
点分隔符（.），类型界限中的&（），catch块中的管道符号（catch（FooException|BarExceptione）
2.如果在赋值运算符处断开，通常的做法是在该符号后断开（比如=，它与前面的内容留在同一行）。
这条规则也适用于foreach语句中的分号。
3.方法名或构造函数名与左括号留在同一行。
4.逗号（,）与其前面的内容留在同一行。
自动换行时缩进至少+4个空格
自动换行时，第一行后的每一行至少比第一行多缩进4个空格（注意：
制表符不用于缩进。
见节）。
当存在连续自动换行时，缩进可能会多缩进不只4个空格（语法元素存在多级时）。
一般而言，两个连续行使用相同的缩进当且仅当它们开始于同级语法元素。
第水平对齐一节中指出，不鼓励使用可变数目的空格来对齐前面行的符号。
空白
垂直空白
以下情况需要使用一个空行：
1.类内连续的成员之间：
字段，构造函数，方法，嵌套类，静态初始化块，实例初始化块。
o例外：
两个连续字段之间的空行是可选的，用于字段的空行主要用来对字段进行逻辑分组。
2.在函数体内，语句的逻辑分组间使用空行。
3.类内的第一个成员前或最后一个成员后的空行是可选的（既不鼓励也不反对这样做，视个人喜好而定）。
4.要满足本文档中其他节的空行要求（比如节：
import语句）
多个连续的空行是允许的，但没有必要这样做（我们也不鼓励这样做）。
水平空白
除了语言需求和其它规则，并且除了文字，注释和Javadoc用到单个空格，单个ASCII空格也出现在以下几个地方：
1.分隔任何保留字与紧随其后的左括号（（）（如if,forcatch等）。
2.分隔任何保留字与其前面的右大括号（}）（如else,catch）。
3.在任何左大括号前（{），两个例外：
o@SomeAnnotation（{a,b}）（不使用空格）。
oString[][]x=foo;（大括号间没有空格，见下面的Note）。
4.在任何二元或三元运算符的两侧。
这也适用于以下“类运算符”符号：
o类型界限中的&（）。
ocatch块中的管道符号（catch（FooException|BarExceptione）。
oforeach语句中的分号。
5.在,:
;及右括号（））后
如果在一条语句后做注释，则双斜杠.}
例外：
单个的注解可以和签名的第一行出现在同一行。
例如：
@OverridepublicinthashCode（）{...}
应用于字段的注解紧随文档块出现，应用于字段的多个注解允许与字段出现在同一行。
例如：
@Partial@MockDataLoaderloader;
参数和局部变量注解没有特定规则。
注释
块注释风格
块注释与其周围的代码在同一缩进级别。
它们可以是/*...*/风格，也可以是.风格。
对于多行的/*...*/注释，后续行必须从*开始，并且与前一行的*对齐。
以下示例注释都是OK的。
/*
*Thisis*evendothis.*/
*/
注释不要封闭在由星号或其它字符绘制的框架里。
Tip：
在写多行注释时，如果你希望在必要时能重新换行（即注释像段落风格一样），那么使用/*...*/。
Modifiers
类和成员的modifiers如果存在，则按Java语言规范中推荐的顺序出现。
publicprotectedprivateabstractstaticfinaltransientvolatilesynchronizednativestrictfp
命名约定
对所有标识符都通用的规则
标识符只能使用ASCII字母和数字，因此每个有效的标识符名称都能匹配正则表达式\w+。
在Google其它编程语言风格中使用的特殊前缀或后缀，如name_,mName,s_name和kName，在Java编程风格中都不再使用。
标识符类型的规则
包名
包名全部小写，连续的单词只是简单地连接起来，不使用下划线。
类名
类名都以UpperCamelCase风格编写。
类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。
现在还没有特定的规则或行之有效的约定来命名注解类型。
测试类的命名以它要测试的类的名称开始，以Test结束。
例如，HashTest或HashIntegrationTest。
方法名
方法名都以lowerCamelCase风
升级会员 