Google Java Style 中文版

一、介绍

 

本文档为Google Java编程规范的完整定义。依照此规范编写的Java源码文件可以被称为Google Style。

 

和其他编程规范指南一样，规范不仅包括了代码的结构美学，也包括了其他一些业界约定俗成的公约和普遍采用的标准。本文档中的规范基本都是业界已经达成共识的标准，我们尽量避免去定义那些还存在争议的地方。

 

 

1.1 术语说明

 

本文档除非特殊说明，否则：

a、class（类）统指普通的class类型、enum枚举类型、interface类型和annotation类型。

b、comment（注释）总是指implementation comments（实现注释，/* */）。我们不使用“文档注释”这样的说法，而会直接说javadoc。

 

其他术语说明，将在文档中需要说明的地方单独说明。

 

 

1.2 文档说明

 

本文档中的代码并不一定符合所有规范。即使这些代码遵循Google Style，但这不是唯一的代码规范。例子中可选的格式风格也不应该作为强制执行的规范。

 

 

 

二、源码文件基础

 

 

2.1 文件名

 

源码文件名由它所包含的顶级class的类名（大小写敏感），加上.java后缀组成。（除了package-info.java文件）。

 

 

2.2 文件编码：UTF-8

 

源码文件使用UTF-8编码。

 

 

2.3 特殊字符

 

2.3.1 空格字符

 

除了换行符外，ASCII水平空白字符（0x20）是源码文件中唯一支持的空格字符。这意味着：

a、其他空白字符将被转义。

b、Tab字符不被用作缩进控制。

 

 

2.3.2 特殊转义字符串

 

任何需要转义字符串表示的字符（例如\b, \t, \n, \f, \r, \', \\等），采用这种转义字符串的方式表示，而不采用对应字符的八进制数（例如 \012）或Unicode码（例如 \u000a）表示。

 

 

2.3.3 非ASCII字符

 

对于其余非ASCII字符，直接使用Unicode字符（例如 ∞），或者使用对应的Unicode码（例如 \u221e）转义，都是允许的。唯一需要考虑的是，何种方式更能使代码容易阅读和理解。

 

注意：在使用unicode码转义，或者甚至是有时直接使用unicode字符的时候，添加一点说明注释将对别人读懂代码很有帮助。

 

例子：

Example	Discussion
String unitAbbrev = "\u03bcs"; // "μs"	Allowed, but there's no reason to do this.
String unitAbbrev = "\u03bcs";	Poor: the reader has no idea what this is.
new int[] {5, 6} 和 int a, b;

 

 

4.8.2.2 当需要时才声明，尽快完成初始化

 

局部变量不应该习惯性地放在语句块的开始处声明，而应该尽量离它第一次使用的地方最近的地方声明，以减小它们的使用范围。

局部变量应该在声明的时候就进行初始化。如果不能在声明时初始化，也应该尽快完成初始化。

 

 

4.8.3 数组

 

4.8.3.1 数组初始化：可以类似块代码处理

 

所有数组的初始化，都可以采用和块代码相同的格式处理。例如以下格式都是允许的：

 

 

 

4.8.3.2 不能像C风格一样声明数组

 

方括号应该是变量类型的一部分，因此不应该和变量名放在一起。例如：应该是 String []  args，而不是  mName ,  kName 。

 

 

5.2 不同类型的标示符规范

 

5.2.1 包名

 

包名全部用小写字母，通过 . 将各级连在一起。不应该使用下划线。

 

 

5.2.2 类名

 

类型的命名，采用以大写字母开头的大小写字符间隔的方式（UpperCamelCase）。

class命名一般使用名词或名词短语。interface的命名有时也可以使用形容词或形容词短语。annotation没有明确固定的规范。

 

测试类的命名，应该以它所测试的类的名字为开头，并在最后加上Test结尾。例如：HashTest 、  HashIntegrationTest。

 

 

5.2.3 方法名

 

方法命名，采用以小写字母开头的大小写字符间隔的方式（lowerCamelCase）。

方法命名一般使用动词或者动词短语。

 

在JUnit的测试方法中，可以使用下划线，用来区分测试逻辑的名字，经常使用如下的结构： test <MethodUnderTest> _ <state> 。例如： testPop_emptyStack 。

测试方法也可以用其他方式进行命名。

 

 

5.2.4 常量名

 

常量命名，全部使用大写字符，词与词之间用下划线隔开。（CONSTANCE_CASE）。

 

常量是一个静态成员变量，但不是所有的静态成员变量都是常量。在选择使用常量命名规则给变量命名时，你需要明确这个变量是否是常量。例如，如果这个变量的状态可以发生改变，那么这个变量几乎可以肯定不是常量。只是计划不会发生改变的变量不足以成为一个常量。下面是常量和非常量的例子：
   

 

 

 

常量一般使用名词或者名词短语命名。

 

 

5.2.5 非常量的成员变量名

 

非常量的成员变量命名（包括静态变量和非静态变量），采用lowerCamelCase命名。

一般使用名词或名词短语。

 

 

5.2.6 参数名

 

参数命名采用lowerCamelCase命名。

应该避免使用一个字符作为参数的命名方式。

 

 

5.2.7 局部变量名

 

局部变量采用lowerCamelCase命名。它相对于其他类型的命名，可以采用更简短宽松的方式。

但即使如此，也应该尽量避免采用单个字母进行命名的情况，除了在循环体内使用的临时变量。

 

即使局部变量是final、不可改变的，它也不能被认为是常量，也不应该采用常量的命名方式去命名。

 

 

5.2.8 类型名

 

类型名有两种命名方式：

 

a、单独一个大写字母，有时后面再跟一个数字。（例如，E、T、X、T2）。

b、像一般的class命名一样（见5.2.2节），再在最后接一个大写字母。（例如，RequestT、FooBarT）。

 

 

5.3 Camel case的定义

 

有时一些短语被写成Camel case的时候可以有多种写法。例如一些缩写词汇，或者一些组合词：IPv6 或者 iOS 等。

为了统一写法，Google style给出了一种几乎可以确定为一种的写法。

 

a、将字符全部转换为ASCII字符，并且去掉 ' 等符号。例如， "Müller's algorithm" 被转换为 "Muellers algorithm" 。

b、将上一步转换的结果拆分成一个一个的词语。从空格处和从其他剩下的标点符号处划分。

    注意：一些已经是Camel case的词语，也应该在这个时候被拆分。（例如 AdWords 被拆分为 ad words）。但是例如iOS之类的词语，它其实不是一个Camel case的词语，而是人们惯例使用的一个词语，因此不用做拆分。

c、经过上面两部后，先将所有的字母转换为小写，再把每个词语的第一个字母转换为大写。

d、最后，将所有词语连在一起，形成一个标示符。

 

注意：词语原来的大小写规则，应该被完全忽略。以下是一些例子：

 

 

 

* 号表示可以接受，但是不建议使用。

 

注意，有些词语在英文中，可以用 - 连接使用，也可以不使用 - 直接使用。例如 “nonempty”和 “non-empty”都是可以的。因此，方法名字为checkNonempty 或者checkNonEmpty 都是可以的。

 

 

 

六、编程实践

 

 

6.1 @override 都应该使用

 

@override annotations只要是符合语法的，都应该使用。

 

 

6.2 异常捕获 不应该被忽略

 

一般情况下，catch住的异常不应该被忽略，而是都需要做适当的处理。例如将错误日志打印出来，或者如果认为这种异常不会发生，则应该作为断言异常重新抛出。

 

如果这个catch住的异常确实不需要任何处理，也应该通过注释做出说明。例如：

 

 

 

例外：在测试类里，有时会针对方法是否会抛出指定的异常，这样的异常是可以被忽略的。但是这个异常通常需要命名为： expected。例如：

 

 

 

6.3 静态成员的访问：应该通过类，而不是对象

 

当一个静态成员被访问时，应该通过class名去访问，而不应该使用这个class的具体实例对象。例如：

 

 

 

6.4 不使用Finalizers 方法

 

重载Object的finalize方法是非常非常罕见的。

 

注意：不应该使用这以方法。如果你认为你必须使用，请先仔细阅读并理解 Effective Java 第七条 “ Avoid Finalizers”。然后不要使用它。

 

 

 

七、Javadoc

 

7.1 格式规范

 

7.1.1 通用格式

 

最基本的javadoc的通用格式如下例：

 

 

或者为单行格式：

 

 

通用格式在任何时候使用都是可以的。当javadoc块只有一行时，可以使用单行格式来替代通用格式。

 

 

7.1.2 段落

 

空白行：是指javadoc中，上下两个段落之间只有上下对齐的 * 字符的行。每个段落的第一行在第一个字符之前，有一个<p>标签，并且之后不要有任何空格。

 

 

7.1.3 @从句

 

所有标准的@从句，应该按照如下的顺序添加：@param、@return、@throws、@deprecated。并且这四种@从句，不应该出现在一个没有描述的Javadoc块中。

当@从句无法在一行写完时，应该断行。延续行在第一行的@字符的位置，缩进至少4个字符单位。

 

 

7.2 摘要片段

 

每个类或者成员的javadoc，都是由一个摘要片段开始的。这个片段非常重要。因为它是类或者方法在使用时唯一能看到的文本说明。

主要摘要只是一个片段，应该是一个名词短语或者动词短语，而不应该是一个完整的句子。但是它应该像一个完整的句子一样使用标点符号。

 

注意：一种常见的错误是以这种形式使用javadoc： /** @return the customer ID */ .这是不对的。应该改为： /** Returns the customer ID. */ .

 

 

7.3 何处应该使用Javadoc

 

至少，Javadoc应该应用于所有的public类、public和protected的成员变量和方法。和少量例外的情况。例外情况如下。

 

 

7.3.1 例外：方法本身已经足够说明的情况

 

当方法本身很显而易见时，可以不需要javadoc。例如：getFoo。没有必要加上javadoc说明“Returns the foo”。

单元测试中的方法基本都能通过方法名，显而易见地知道方法的作用。因此不需要增加javadoc。

 

注意：有时候不应该引用此例外，来省略一些用户需要知道的信息。例如：getCannicalName 。当大部分代码阅读者不知道canonical name是什么意思时，不应该省略Javadoc,认为只能写/** Returns the canonical name. */ 。

 

 

7.3.2 例外：重载方法

 

重载方法有时不需要再写Javadoc。

 

 

7.3.3 例外：可选的javadoc

 

一些在包外不可见的class和成员变量或方法，根据需要，也可以使用javadoc。当一个注释用以说明这个类、变量或者方法的总体目标或行为时，可以使用Javadoc。