Google Java编程风格规范

发表于 | 分类于 | 阅读次数:
字数统计: 4,641 | 阅读时长 ≈ 17

编程也需要好的习惯和规范，翻译自《Google Java编程风格指南》(链接见最后)。

源文件基础

文件名

文件名以最顶层的类名来命名，大小写敏感，文件扩展名为.java.

文件编码

源文件编码的格式采用UTF-8.

特殊字符

空白字符

除了行结束符序列，ASCII水平空格字符（0x20,即空格）是源文件中唯一允许出现的空白字符。也就是说：

  1. 其它情况下出现的空白字符都要进行转义；
  2. 制表符不用于缩进；

    特殊转义序列

    对于具有特殊转义序列的任意字符（\b,\t,\n,\f,\r,\”,\’以及\），我们使用它的转义序列，而不是相应的八进制（比如\012）或Unicode（比如\u000a)转义。

    非ASCII字符

    对于剩余的非ASCII字符，是使用实际的Unicode字符（比如∞），还是使用等价的Unicode转义符（比如\u221e），取决于哪个能让代码更易于阅读和理解。

Tip:在使用Unicode转义符或是一些实际的Unicode字符时，建议做些注释给出解释，这有助于别人阅读和理解。

源文件结构

按顺序地，一个源文件包含：

  1. 许可证和版权信息（如有需要）
  2. package语句
  3. import语句
  4. 一个顶级类（只有一个）

以上每个部分用一个空行隔开。

许可证和版权信息

如果一个文件包含许可证和版权信息，那么它应该放在文件的最前面。

package语句

package语句不换行，列限制（4.4节）并不适用于package语句。（即package语句写在一行里）

import语句

import不要使用通配符

即，不要出现类似这样的import语句：import java.util.* ;

不要换行

import语句不换行，列限制（4.4节）并不适用于import语句。（即每个import语句独立成行）

顺序和间距

import语句可以分为以下几组，按照下面的顺序，组各由一个空行分隔：

  1. 所有的静态导入独立成组
  2. com.google导入（源文件在com.google包下）
  3. 第三方的包，每个顶级包一组，字典序。例如：android,com,junit,org,sun
  4. java包导入
  5. javax导入

组内不空行，按字典排序。

类声明

只有一个顶级类声明

每个顶级类都在一个和它同名的源文件中（当然，包含.java后缀）

例外，package-info.java,该文件中可没有package-info类。

类成员顺序

不存在唯一的通用法则，每种类以某种逻辑排列它的成员，维护者应该能解释这种排列逻辑。比如新的方法不应该总是添加在类的最后面，因为这是按照时间顺序而不是某种逻辑来排列的。

tip:永不分离的重载：当一个类有多个构造函数，或者是多个同名方法，它们应该按照顺序出现在一起，中间不要放进其它函数、方法。

格式

术语说明：块状结构指的是一个类、方法或构造函数的主体。需要注意的是，数组初始化中的初始值可被选择性的视为块状结构。

大括号

使用大括号（即便是可选的）

大括号与if、else、for、do、while语句一起使用，即使只有一条语句（或是空），也应该把大括号写上。

非空块：K&R风格

对于非空块和块状结构，大括号遵循Kernighan和Ritche风格：

  • 左大括号前不换行
  • 左大括号后换行
  • 右大括号前换行
  • 如果右大括号是一个语句、函数体或类的终止，则右大括号后换行；否则不换行。例如，如果右大括号后面是else或逗号，则不换行。

示例：

1
2
3
4
5
6
7
8
9
return new MyClass() {
  if (condition()) {
    try {
      something();
    } catch (ProblemException e) {
      recover();
    }
  }
};

后续给出了enum类的一些例外。

空块：可以用简洁版本

一个空的块状结构里什么也不包含，大括号可以简洁地写成{}，不需要换行。例外：如果它是一个多块语句的一部分（if/else或try/catch/finally），即使大括号内没内容，右大括号也要换行。

示例:

1
void doNothing() {}

块缩进：2个空格

每当开始新的块，缩进增加2个空格，当块结束时，缩进返回先前的缩进级别，缩进级别适用于代码和注释。

一行一个语句

每个语句后要换行。

列限制：80或100

一个项目可以选择一行80个字符或100个字符的列限制，除了下述例外，任何一行如果超过这个字符数限制，必须自动换行。

例外：

  1. 不可能满足列限制的行（例如Javadoc中的一个厂URL，或是一个厂的JSNI方法参考）；
  2. package和import语句；
  3. 注释中那些可能被剪切并粘贴到shell中的命令行；

自动换行

术语说明：line-wrapping指的是一行代码为了避免超出列限制而被分为多行。

很多时候，对于一段代码会有好几种有效地自动换行方式。

Tip:提取方法或局部变量可以在不换行的情况下解决代码过长的问题（合理缩短命名长度）。

从哪断开

自动换行的基本准则：更倾向于在更高的语法级别处断开。

  1. 在非赋值运算符处断开：在该符号前断开（比如+，它将位于下一行）。这条规则也适用于以下“类运算符”符号，点分隔符（.），类型界限中的&（<T extends Foo & Bar>），catch块中的管道符号（catch (FooException | BarException e)；
  2. 在赋值运算符处断开：通常做法是在该符号后断开（比如=，它与前面的内容留在同一行）。这条规则也适用于foreach语句中的分号；
  3. 方法名或构造函数名与左括号留在同一行；
  4. 逗号（,）与其前面的内容留在同一行；

自动换行时缩进至少+4个空格

自动换行时，第一行后的每一行至少比第一行多缩进4个空格（注意：制表符在前面说过了，制表符不用于缩进）。当存在连续自动换行时，缩进可能会多缩进不只4个空格（语法元素存在多级时）。一般而言，两个连续行使用相同的缩进当且仅当他们开始于同级语法元素。

空白

垂直空白

以下情况需要使用一个空行：

  1. 类内连续的成员之间：字段，构造函数，方法，潜入类，静态初始化块，实例初始化块；
    • 例外：两个连续的字段之间的空行是可选的，用于字段的空行主要是用来对字段进行逻辑分组。
  2. 在函数内，语句的逻辑分组间使用空行；
  3. 类内的第一个成员前或最后一个成员后的空行是可选的（既不鼓励也不反对这样做，视个人喜好而定）；
  4. 满足本规范个其它关于空行的要求。

多个连续的空行是允许的，但是没必要这么做（也不鼓励这样做）。

水平空白

除了语言需求和其它规则，并且除了文字，注释和Javadoc用到单个空格，单个ASCII空格也出现在以下几个地方：

  1. 分割任何保留字与紧随其后的左括号（(）（如if、for或catch等）

    1
    2
    3
    for (; ; ) {
    }

  2. 分割任何保留字与其前面的右大括号（}）（如else,catch）

    1
    2
    3
    4
    5
    try {
          something();
        } catch (ProblemException e) {
          recover();
        }

  3. 在任何大括号前（{）。但是有两个例外：

    • @SomeAnnotation({a, b})（不使用空格）
    • String[][] x = {{"foo"}};（大括号间没有空格，见第八条下面的那点）
  4. 任何二元或三元运算符的两侧。这也适用于以下“类运算符”符号：
    • 类型界限中的&（<T extends Foo & Bar>）
    • catch块中的管道符号|（catch (FooException | BarException e)）
    • foreach语句中的分号
  5. 在, : ;及右括号（)）后
  6. 如果在一条语句后做注释，则双斜杠两边都需要空格，可以允许多个空格，但是没有必要
  7. 类型和变量之间，比如：List list
  8. 数组初始化中，大括号内的空格是可选的，即new int[] {5, 6}和new int[] {5, 6 }都是可以的
    • 这个规则并不要求或禁止一行的开关或结尾需要额外的空格，只对内部空格做要求

水平对齐：never required

术语说明：水平对齐指的是通过增加可变数量的空格来使某一行的字符与上一行的相应字符对齐。

这是允许的，但是Google编程风格对此不作要求。

Tip:对齐可增加代码可读性，但它为日后的维护带来问题。考虑未来某个时候，我们需要修改一堆对齐的代码中的一行。这可能导致原本很漂亮的对齐代码变得错位。很可能它会提示你调整周围代码的空白来使这一堆代码重新水平对齐(比如程序员想保持这种水平对齐的风格)，这就会让你做许多的无用功，增加了reviewer的工作并且可能导致更多的合并冲突。

用小括号来限定组：推荐

除非认为去掉小括号不会使代码被误解，或者去掉小括号能让代码更易于阅读，否则我们不应该去掉小括号。没有理由假设读者能记住整个Java运算符优先级表。

具体结构

枚举类

枚举常量间用逗号隔开，换行可选。

没有方法和文档的枚举类可写成数组初始化的格式：

1
private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }

由于枚举类也是一个类，因此所有适用于其它类的格式规则也适用于枚举类。

变量声明

每次只声明一个变量

不要使用组合声明，比如int a, b;。

需要时才声明，并尽快进行初始化

不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法)，而是在第一次需要使用它时才声明。 局部变量在声明时最好就进行初始化，或者声明后尽快进行初始化。

数组

数组初始化：可写成块状结构

数组初始化可以写成块状结构，比如，下面的写法都是OK的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
new int[] {
  0, 1, 2, 3
}
new int[] {
  0,
  1,
  2,
  3
}
new int[] {
  0, 1,
  2, 3
}
new int[]
    {0, 1, 2, 3}

非C风格的数组声明

中括号是类型的一部分：String[] args， 而非String args[]。

switch语句

术语说明：switch块的大括号内是一个或多个语句组。每个语句组包含一个或多个switch标签(case FOO:或default:)，后面跟着一条或多条语句。

缩进

与其它块状结构一致，switch块中的内容缩进为2个空格。

每个switch标签后新起一行，再缩进2个空格，写下一条或多条语句。

Fall-through:注释

在一个switch块内，每个语句组要么通过break, continue, return或抛出异常来终止，要么通过一条注释来说明程序将继续执行到下一个语句组，任何能表达这个意思的注释都是OK的(典型的是用// fall through)。这个特殊的注释并不需要在最后一个语句组(一般是default)中出现。示例：

1
2
3
4
5
6
7
8
9
10
11
switch (input) {
  case 1:
  case 2:
    prepareOneOrTwo();
    // fall through
  case 3:
    handleOneTwoOrThree();
    break;
  default:
    handleLargeNumber(input);
}

default的情况要写出来

每个switch语句都要包含一个default语句组，即使什么代码都不包含。

注解（Annotations）

注解紧跟在文档块后面，应用于类、方法和构造函数，一个注解独占一行。这些换行不属于自动换行，因此缩进级别不变。例如：

1
2
3
@Override
@Nullable
public String getNameIfPresent() { ... }

例外：单个的注解可以和签名的第一行出现在同一行。例如：

1
@Override public int hashCode() { ... }

应用于字段的注解紧随文档块出现，应用于字段的多个注解允许与字段出现在同一行。例如：

1
@Partial @Mock DataLoader loader;

参数和局部变量注解没有特定规则。

注释

块注释风格

块注释与其周围的代码在同一缩进级别，以下注释都是OK的：

1
2
3
4
/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

修饰符

类和成员的修饰符如果存在，则按Java语言规范中推荐的顺序出现。

1
public protected private abstract static final transient volatile synchronized native strictfp

命名约定

对所有标识符都有通用的规则

标识符只能使用ASCII字母、数字和下划线，字母大小写敏感，因此每一个有效地标识符名称都能匹配正则表达式\w+.

在Google其它编程语言风格中使用的特殊前缀或后缀，如name_，mName，s_name和kName,在Java编程风格中都不再使用。

标识符类型的规则

包名

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

类名

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

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

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

方法名

类名都以UpperCamelCase风格编写。

方法名通常是动词或动词短语。

在JUnit的测试方法中，可以使用下划线，用来区分测试逻辑的名字，经常使用如下的结构，例如：testPop_emptyStack.并不存在唯一正确的方式来命名测试方法。

常量名

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Constants
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(',');  // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

这些名词通常是名词短语。

非常量字段名

非常量字段名以lowerCamelCase风格编写。

参数应该避免用单个字符命名。

局部变量名

局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。

虽然缩写更宽松，但还是要避免用单字符进行命名，除了临时变量和循环变量。

即使局部变量是final和不可改变的，也不应该把它示为常量，自然也不能用常量的规则去命名它。

类型变量名

类型名有两种命名方式：
a、单独一个大写字母，有时后面再跟一个数字。（例如，E、T、X、T2）。
b、像一般的class命名一样（见5.2.2节），再在最后接一个大写字母。（例如，RequestT、FooBarT）。

编程实践

@Override：能用则用

只要是合法的，就要把@Override注解给用上。

捕获的异常：不能忽视

对捕获的异常不作响应是极少正确的。如果确实是不需要在catch中做任何响应，需要做注释甲乙说明。

例外：在测试中，如果一个捕获的异常被命名为expected，则它可以被不加注释地忽略。下面是一种非常常见的情形，用以确保所测试的方法会抛出一个期望中的异常， 因此在这里就没有必要加注释。

1
2
3
4
5
try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

静态成员：使用类进行调用

使用类名调用静态的类成员，而不是具体某个对象或表达式。

Finalizers:禁用

极少会去重载Object.finalize.

tip:不要使用finalize。如果你非要使用它，请先仔细阅读和理解Effective Java 第7条款：“Avoid Finalizers”，然后不要使用它。

Javadoc

格式

一般形式

Javadoc块额基本格式如下所示：

1
2
3
4
5
/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

或者是以下单行形式：

1
/** An especially short bit of Javadoc. */

基本格式总是OK的。当整个Javadoc块能容纳于一行时(且没有Javadoc标记@XXX)，可以使用单行形式。

哪里需要使用Javadoc

至少在每个public类及它的每个public和protected成员处使用Javadoc，以下是一些例外：

例外：不言自明的方法

对于简单明显的方法如getFoo，Javadoc是可选的(即，是可以不写的)。这种情况下除了写“Returns the foo”，确实也没有什么值得写了。

单元测试类中的测试方法可能是不言自明的最常见例子了，我们通常可以从这些方法的描述性命名中知道它是干什么的，因此不需要额外的文档说明。

tip:如果有一些相关信息是需要读者了解的，那么以上的例外不应作为忽视这些信息的理由。例如，对于方法名getCanonicalName， 就不应该忽视文档说明，因为读者很可能不知道词语canonical name指的是什么。

例外：重载

如果一个方法重载了超类中的方法，那么Javadoc并非必需的。

可选的Javadoc

对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为，那么这个注释应该写成Javadoc，这样更统一更友好。

参考文献