Java 编程规范 参考 Google

1.命名规范

** 1.1 驼峰式命名法（CamelCase）** 驼峰式命名法分大驼峰式命名法（UpperCamelCase）和小驼峰式命名法（lowerCamelCase）;前者是指每个单词的第一个字母都大写，后者是指除了第一个单词，每个单词的第一个字母都大写。 有时，我们有不只一种合理的方式将一个英语词组转换成驼峰形式，Google指定了以下的转换方案:

名字从散文形式(prose form)开始:

• 1.把短语转换为纯ASCII码，并且移除任何单引号。例如：”Müller’s algorithm”将变成”Muellers algorithm”。
• 2把这个结果切分成单词，在空格或其它标点符号(通常是连字符)处分割开。 推荐：如果某个单词已经有了常用的驼峰表示形式，按它的组成将它分割开(如”AdWords”将分割成”ad words”)。 需要注意的是”iOS”并不是一个真正的驼峰表示形式，因此该推荐对它并不适用。
• 3.现在将所有字母都小写(包括缩写)，然后将单词的第一个字母大写：判断用大驼峰式还是小驼峰式命名。
• 4最后将所有的单词连接起来得到一个标识符。

1.2 标识符类型的规则

1.2.1 包名

全部小写，连续的单词只是简单的连起来，并不使用下划线。

1.2.2 类名

以UpperCamelCase风格编写； 测试类以它要测试的类名称开始，以Test结束。

1.2.3 方法名

以lowerCamelCase风格编写； 下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是：test<MethodUnderTest>_<state>，例如testPop_emptyStack。 并不存在唯一正确的方式来命名测试方法。

1.2.4 常量名

命名模式为 CONSTANT_CASE ,全部字母大写，用下划线分隔单词； 常量必需是真的一直不变的。

1.2.5 非常量字段名、参数名、局部变量名

以 lowerCamelCase 风格编写。

1.2.6 类型变量名

类型变量可用以下两种风格之一进行命名：

• 这里是列表文本单个的大写字母，后面可以跟一个数字(如：E, T, X, T2)。
• 这里是列表文本以类命名方式(1.2.2节)，后面加个大写的T(如：RequestT, FooBarT)。

2 源文件基础

2.1 文件名

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

2.2 文件编码：UTF-8

2.3 特殊字符

2.3.1 空白字符

除了行结束符序列，ASCII水平空格字符(0x20，即空格)是源文件中唯一允许出现的空白字符。 PS : 意味着其他字符串中的空白字符都要进行转义，以及制表符不用于缩进。

2.3.2 特殊转义序列

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

2.3.3 非ASCII字符

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

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

PS：有必要时大胆测试使用非ASCII字符。

3 源文件结构

3.1许可证或版权信息

置于文件最前面。

3.2 package语句

不换行（写在一行里）。

3.3 import 语句

3.3.1 import不要使用通配符

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

3.3.2 不要换行

每个import 语句独立成行

3.3.3 顺序和间距

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

• 2. com.google imports(仅当这个源文件是在com.google包下)
• 3. 第三方的包。每个顶级包为一组，字典序。例如：android, com, junit, org, sun
• 4. java imports
• 5. javax imports

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

3.4 类声明

3.4.1 只有一个顶级类声明

每个顶级类都在一个与它同名的源文件中(当然，还包含.java后缀)。

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

3.4.2 类成员顺序

每个类应该按某种逻辑去排序它的成员。 重载的多个构造函数或同名方法按顺序出现在一起，中间不要放入其他类。

PS:方便维护。（不要按时间顺序）

4 格式

4.1 大括号

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

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

4.1.2 非空块：K & R 风格

对于非空块和块状结构，大括号遵循Kernighan和Ritchie风格 (Egyptian brackets):

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

4.1.3 空块 可以使用简洁版本

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

4.2 块缩进：2个空格

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

4.3 一行一个语句

4.4 列限制：80或100 字符

4.5 自动换行

术语说明：一般情况下，一行长代码为了避免超出列限制(80或100个字符)而被分为多行，我们称之为自动换行(line-wrapping)。

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

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

4.5.1 从哪里断开

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

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

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

自动换行时，第一行后的每一行至少比第一行多缩进4个空格。 当存在连续自动换行时，缩进可能会多缩进不只4个空格(语法元素存在多级时)。一般而言，两个连续行使用相同的缩进当且仅当它们开始于同级语法元素。

4.6 空白

4.6.1 垂直空白

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

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

PS：没必要做多行连续空白。

4.6.2 水平空白

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

• 1.  分隔任何保留字与紧随其后的左括号(()(如if, for catch等)。
     

• 2. 分隔任何保留字与其前面的右大括号(})(如else, catch)。
• 3. 在任何左大括号前({)，两个例外： @SomeAnnotation({a, b})(不使用空格)。 String[][] x = foo;(大括号间没有空格，见下面的Note)。
• 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 }都是可以的。

Note：这个规则并不要求或禁止一行的开关或结尾需要额外的空格，只对内部空格做要求。

4.6.3 水平对齐：不做要求

PS：没必要，可能对维护造成麻烦。

4.7 用小括号来限定组 : 推荐

4.8 具体结构

4.8.1 枚举类

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

4.8.2 变量声明

4.8.2.1 每次只声明一个变量

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

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

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

4.8.3 数组

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

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

4.8.3.2 非C风格的数组声明

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

4.8.4 switch语句

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

4.8.4.1 缩进

与其它块状结构一致，switch块中的内容缩进为2个空格。 每个switch标签后新起一行，再缩进2个空格，写下一条或多条语句。

4.8.4.2 Fall-through：注释

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

4.8.4.3 default的情况要写出来

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

_ 4.8.5 注解(Annotations)_

注解紧跟在文档块后面，应用于类、方法和构造函数，一个注解独占一行。这些换行不属于自动换行(第4.5节，自动换行)，因此缩进级别不变。 例外：单个的注解可以和签名的第一行出现在同一行。应用于字段的注解紧随文档块出现，应用于字段的多个注解允许与字段出现在同一行。

4.8.6 注释

4.8.6.1 块注释风格

块注释与其周围的代码在同一缩进级别。它们可以是/* ... /风格，也可以是// ...风格。对于多行的/ ... /注释，后续行必须从开始， 并且与前一行的*对齐。

Tip：在写多行注释时，如果你希望在必要时能重新换行(即注释像段落风格一样)，那么使用/* ... */。

_ 4.8.7 Modifiers_

类和成员的modifiers如果存在，则按Java语言规范中推荐的顺序出现。 public protected private abstract static final transient volatile synchronized native strictfp

5 编程实践

5.1 @override 能用则用 5.2 捕获的异常 不能忽视

(典型的响应方式是打印日志，或者如果它被认为是不可能的，则把它当作一个AssertionError重新抛出。) 如果它确实是不需要在catch块中做任何响应，需要做注释加以说明。

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

5.3 静态成员:使用类进行调用 5.4 Finalizers: 禁用

极少会去重写Object.finalize。

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

6 Javadoc

6.1 格式

6.1.1 一般形式 Javadoc块的基本格式如下所示：

/**
  * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */

public int method(String p1) { ... }

或者是以下单行形式：

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

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

6.1.2 段落

空行(即，只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。 除了第一个段落，每个段落第一个单词前都有标签<p>，并且它和第一个单词间没有空格。

6.1.3 Javadoc标记

标准的Javadoc标记按以下顺序出现：, @return, @throws, @deprecated, 前面这4种标记如果出现，描述都不能为空。 当描述无法在一行中容纳，连续行需要至少再缩进4个空格。

6.2 摘要片段

每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的，在某些情况下，它是唯一出现的文本，比如在类和方法索引中。

这只是一个小片段，可以是一个名词短语或动词短语，但不是一个完整的句子。它不会以A {@code Foo} is a...或This method returns...开头, 它也不会是一个完整的祈使句，如Save the record...。然而，由于开头大写及被加了标点，它看起来就像是个完整的句子。

Tip：一个常见的错误是把简单的Javadoc写成/** @return the customer ID /，这是不正确的。它应该写成/* Returns the customer ID. */。

6.3 哪里需要使用Javadoc

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

6.3.1 例外：不言自明的方法

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

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

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

6.3.2 例外：重写

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

6.3.3 可选的Javadoc

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