本文档用于Java编程语言的Google源代码编码标准的完整定义。Java源文件定义为Google风格。
于其他编程风格指南一样，所涉及的问题不止包含代码格式美化，还包括其他类型的约定或者编码标准。 但是本文档主要关注普遍遵循的严格规则，并避免提供意义不明的可执行建议（无论任何方式）。
本文件中除非另有说明：
class包含用于表示普通类、枚举、接口或注解类型（@interface）成员用于表示嵌套类、字段、方法或构造方法，也就是说除了初始设定和注释的顶级内容注释总是实现注释，我们不使用短语“文档注释”，而是使用常规术语javadoc
其他术语说明会在整个文件中偶尔出现
译者注：嵌套类即内部类
本文档中的示例代码是非规范的。也就是说虽然示例是Google风格，但它们可能没有说明代码的唯一方式。 示例中的可选格式也不应作为规则强制执行。
2. 源文件基础
源文件名包含顶级类并区分大小写（并且只有一个），加上.java扩展名。
源码文件编码必须是 UTF-8
译者注：因为不同操作系统默认的换行符不一样，请统一使用\n(LF)作为代码换行符。
除了行终止符序列，ASCII水平空格字符（0x20）是唯一出现在源文件中的任何位子的空白字符。 这意味着：
- 字符串和字符文字中的其他空格字符都被转义
- 制表符(
0x09)不可以用于缩紧
任何字符包含特别字符序列（\b \t \n \f \r \" \'和 \\），使用该序列不应该转成八进制或Unicode转义。
对于其他非ASCII字符，使用Unicode字符或等效Unicode转义符。选择仅取决于那种使代码更易于阅读和理解， 尽管Unicode在字符串文字之外转义并强烈不建议使用注释。
小贴士：在Unicode特别字符，有时即使使用Unicode字符，解释性注释也会非常有用。
| 示例 |
说明 |
| String unitAbbrev = "μs"; |
最好: 完美清晰的代码不需要注释 |
| String unitAbbrev = "\u03bcs"; // "μs" |
允许，但是没必要这么写 |
| String unitAbbrev = "\u03bcs"; // Greek letter mu, "s" |
允许，但是容易出错 |
| String unitAbbrev = "\u03bcs"; |
差：读者不知道这是什么 |
| return '\ufeff' + content; // byte order mark |
好： 对于不打印的字符使用转义，并且在必要时注释。 |
小贴士：由于担心某些程序可能无法正确处理非ASCII字符，因此不要让代码可读性降低。 如果发生这种情况，那些程序会被破坏，必须修复
3. 源码结构
源文件顺序包括：
- 许可证或版权许可（如果有）
Package声明Import语句- 恰好一个顶级类
恰好一个空白行将每个部分区分开
译者注：请在顶级类之前加入必要的文档注释，并包含作者信息。
3.1. 许可证或版权讯息
如果许可或者版权信息术语文件，这放在这里
译者注：许可信息通常包含两部分，完整许可文件和版权信息（Copyright段落）。 完整文件请放在项目根目录下，代码仅包含版权信息。
3.2. Package语句
Package语句是不换行的。列限定（第4.4节，列限制：100）不用于包语句。
3.3. Import语句
通配符导入，静态或普通类都不能使用。
Import语句是不换行的。列限定（第4.4节，列限制：100）不用于导入语句。
导入次序如下：
- 所有静态导入独立一行。
- 所有非静态导入独立一行。
如果同时包含静态和非静态导入，一个空白行将两块分开，导入语句之间不包含任何空白行。
在每个快中，导入名称以ASCII排序显示。（注意：这与ASCII排序的import语句不同，因为.在;之前排序。）
静态导入不用于静态嵌套类，他们是通过正常导入的方式导入的。
每一个源文件只能拥有一个顶级类
你选择成员和初始化的顺序可能会对学习造成很大的影响，但是没有一个正确的方法可以做到这一点， 不懂类可以有不同的方式排序内容。
重要的是每个类使用的逻辑顺序一样，如果被问到维护者可以解释它。例如新方法被习惯性的加到末尾。 因为这将产生“按时间顺序添加”排序，这不是逻辑排序。
术语注意：块结构是指类、方法或者构造方法的主体。请注意，通过关于数组初始化定义在4.8.3.1， 可以选择将任何数组设定项视为类似块的结构。
4.1.1. 使用花括号（即使是可选的）
花括在在使用if else for do 和 while语句，即使是空或者只有一条语句，也应该使用花括号。
对于非空块和类块接口，花括号遵循Kernighan和Ritchie样式（“埃及括号”）：
- 在花括号开始前密友断行
- 花括号开始后换行
- 关闭花括号前换行
- 仅在花括号终止、构造方法或命名类主体时，花括号后换行。例如如果后面是
else或逗号，则在花括号后没有换行。
例如：
return () -> {
while (condition()) {
method();
}
};
return new MyClass() {
@Override public void method() {
if (condition()) {
try {
something();
} catch (ProblemException e) {
recover();
}
} else if (otherCondition()) {
somethingElse();
} else {
lastThing();
}
}
};
一些枚举类例外在第4.8.1节列出
空块或者类块接口可以采用R&B样式（如4.1.2节所述）。或它可以在打开后立即关闭。 在花括号之间没有字符或者换行符，除非它是多块语句的一部分（直接包含多块语句包括 if/else 或 try/catch/finally）
例如：
// 这是受欢迎的
void doNothing() {}
// 这种同样受欢迎
void doNothingElse() {
}
// 这是不可接受的：多块语句中没有简洁的空块。
try {
doSomething();
} catch (Exception e) {}
4.2. 空缩紧： +2空格
每次打开新的块或块构造，缩紧会增加两个空格。当块结束时，缩紧返回到之前的缩紧级别。 缩紧级别适用于整个块中的代码和注释。（参见第4.1.2节的示例， 非空块：K&R样式）
每条语句后面都有一个换行符。
Java代码的列限制为100个字符。字符表示任何Unicode码。除非另有说明，否则任何超出此限制都必须换行， 如4.5节“换行”所述。
每一个Unicode码为一个字符，即使显示宽度大于或者小于。如果使用全角字符， 你可以选择比此规则严格要求更早的位置换行。
译者注：请使用等宽字体，另不建议在代码中使用Unicode（即ASCII以外的字符）。
例外：
- 不遵守列限制的行（例如Javadoc中的长URL或长JSNI方法引用）
- package和import语句（参见3.2.Package语句和3.3.Import语句）
- 注释中的命令行可以剪切-黏贴到shell中
术语注意：当可能合法占用单行的代码为多行时，此活动会杭杭。
没有全面的，确定性的公式显示如何在不同情况下换行，通常有机种有效的方法来包装同一段代码。
注意：虽然换行典型原因是为了避免溢出列限制，但即使实际符合列限制的代码也可能由作者自行决定是否换行
小贴士：提取方法或者局部变量可以解决问题而无需换行
换行的主要原因是更喜欢在更高的语句断开。
- 当非复值运算符在断行时，断点出现在符号之前。（请注意，这与C++和Javascript在Google风格中使用的作法不同）
- 这也适用与以下“操作类似”的符号
- 点符（
.）
- 方法参考的两个冒号（
::）
- 类型绑定符号（
<T extends Foo & Bar>）
- 捕获块中的管道（
catch (FooException | BarException e)）
- 当复值运算符在断行处执行时，断点通常出现在符号之后，但是任何一种方式都是可接受的
- 这也适用于增强性
for（“foreach”）语句中的复值操作符
- 方法或构造方法名称后面的左括号（
(）的后面
- 逗号（
,）的后面
- 在Lambda中的箭头旁边的符号永远不会破坏，除非Lambda的主体由单个无支撑表达式组成。则箭头后面可能出现断点。
例如：
MyLambda<String, Long, Object> lambda =
(String label, Long value, Object obj) -> {
...
};
Predicate<String> predicate = str ->
longExpressionInvolving(str);
注意：换行的主要目的是表达清晰的代码，而不一定适合最小行数的代码
换行时，第一行之后每行从原始缩紧至少+4
当存在多个连续行的时候，根据需要压缩可以变化超过+4。通常当且仅当以行元素开始头时，两个连续行使用相同的缩紧级别。
关于水平对齐在4.6.3节解决可变数量空格与前一行对齐。
一个单空白行总是出现：
- 在类的连续成员或初始值之间：字段，构造方法，方法，嵌套类，静态初始化和实例初始设定项
- 例外：一个空白行在两个连续字段之间（它们之间没有代码）是可选的。根据需要使用这样的空白行来 创建字段的逻辑分组
- 例外：枚举常量之间的空白行在4.8.1节中介绍
- 根据本文档其他部分要求（例如第3节 源文件结构和第3.3节 import语句）
单个空白行也可以出现任何提高可读性的地方，例如在代码组织或者逻辑子部分的语句之间。 第一个成员或者初始化程序之前，或在该类的最后一个成员或初始化程序之后的空白行是不鼓励的。
允许多个连续的空白行，但是从来不需要（或鼓励）。
除了语言或其他样式规则要求以外，除了文字、注释和javadoc之外，单个ASCII空间也仅出现以下位置
- 将任何保留字（
if for 或 catch）从该行后面的开括号（(）或行分离出来。
- 将任何保留字（
else 或 catch）与该行之前的花括号（‘}’）分开
- 在开括号之前，有两点以外：
@SomeAnnotation({a, b}) 没有使用空格String[][] x = {{"foo"}}; 没有空格必须在 {{ 之间，参考下面第8项
- 在任何二元或三元运算符的两边，也适用以下"类似运算符"的符号：
- 联合类型中
&符号： <T extends Foo & Bar>
- 用于处理多个异常的catch块管道：
catch (FooException | BarException e)
- 增强性
for（“foreach”）中的冒号（:）
- Lambda表达式中的箭头：
(String str) -> str.length()
但是请不要：
- 他是方法定义引用俩个冒号（
::），类似于Object::toString
- 点分隔符（
.）写成object.toString()
- 在（
,:;）之后或者关闭符号（)）之前
- 在双斜杠（
//）的两侧开始一行结束注释。这里允许多个空格，但不是必须的。
- 在声明的类型和变量之间：
List<String> list
- 在数组的初始化的两个花括号之间可选：
new int[] {5, 6} 和 new int[] { 5, 6 } 都是有效的
- 在类型注解和
[]或...之间
该规则从未被解释为在开头或结尾处要求或禁止以外的空间，它只涉及内部空间。
术语注意：水平对齐是在代码中添加可变数量的额外空格的作法，目的是是某些标记直接出现在前一行某些标记的下面。
这种做法是允许的，但是Google风格不需要这种做法。甚至不需要在已经使用过的地方保持水平对齐。
这是一个没有使用对齐的示例，然后使用对齐：
private int x; // 这个还好
private Color color; // 这个一样
private int x; // 允许但是后面的内容
private Color color; // 可能会变得不对齐
小贴纸：对齐可以提高可读性，但是也为将来的维护带来问题。考虑一下以后的代码变化。 这种改变可能会是以前令人愉悦的代码格式化变得严重，并且这是允许的。更常见的是他会提示调整附近的空格， 这可能引起一系列的重新格式化。这种单线改变具有“爆炸半径”。这可能导致无意义的工作，但是他会破坏历史信息， 影响代码审查，并加重冲突。
只有当作者和审查者同意没有合理的机会将代码误解为错误，才会省略可选分组括号，也不会使代码更容易阅读。 假设每个读者都记住整个Java运算符优先级是不合理的。
在枚举常量后面的每个逗号后，换行符是可选的。还允许额外的空白（通常只有一行）。或许以下这样：
private enum Answer {
YES {
@Override public String toString() {
return "yes";
}
},
NO,
MAYBE
}
没有方法且没有关于常量的枚举类是可选格式化的，就好像他是一个数组初始化一样（参考数组初始化第4.8.3.1节）
private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
由于枚举类是类，因此也适用于格式化格式化类的其他规则。
每个变量声明（字段或内部）只声明一个变量：如 int a, b; 不使用。
例外：for循环的标头中可接受多个变量声明。
局部变量在包含块或者类块构造的开始不声明。局部变量被声明为接近他们首次使用的点（在合理范围内）， 以最小化他们的范围。局部变量声明通常具有初始化代码，或在声明时候立即初始化。
任何数组初始化可以选择格式化，就像它是“块状结构”一样。例如立下都是有效的（不是详细的列表）：
new int[] { new int[] {
0, 1, 2, 3 0,
} 1,
2,
new int[] { 3,
0, 1, }
2, 3
} new int[]
{0, 1, 2, 3}
方括号构成类型的一部分，而不是变量：String[] args 而不是String args[]
术语注意：开switch块内的一个或多个语句组。每条语句都有一个或多个switch标签 （例如 case FOO: 或 default:）组成。后跟一个或多条语句（或者，对于最后一条语句组，零个或多条语句。）
与其他任何块一样，switch块缩2个空格。
每个switch标签之后使用新的一行再缩进2个空格。后面是一条或多条语句。
在switch块中，每条语句组要么终止（跟着 break continue return 或抛出异常），要么用注释标记， 表示会进入到下一个语句组。任何说明Fall-through的注释都是必要的（通常用//）。 在switch块的最后一条语句组不需要这种注释。例如：
switch (input) {
case 1:
case 2:
prepareOneOrTwo();
// fall through
case 3:
handleOneTwoOrThree();
break;
default:
handleLargeNumber(input);
}
注意，在case 1:之后不需要注释，仅在语句组末尾。
每个switch语句都包含default语句组，即使后面没有代码。
例外：enum类型的switch块是可以忽略default语句组的。如果他包含该类型的所有可能值的情况。 这能让IDE或其他静态分析工具提交任何错过的问题。
注解作用与类、方法、或构造方法的文档注释块之后，并且每个注解都在对应的行上（即每行一个注解）。 这些换行不影响本身的缩进（第4.5节 换行）。
@Override
@Nullable
public String getNameIfPresent() { ... }
例外：单个无参数注释可以与声明第一行一起出现，例如：
@Override public int hashCode() { ... }
用于字段的注解也可以在文档注释后出现，但在这种情况下，可能会一起列出多个注解（可能包含参数）；例如：
@Partial @Mock DataLoader loader;
在参数、局部变量或类型上注解没有特定规则格式化。
译者注：为了方便阅读 请不要把注解和方法或变量声明放到同一行，仅当变量为方法的参数的时候放在同一行。
本节介绍普通注释，javadoc的文档注释会在第7节说到。
任何断行之前可能包含多个空格，后面是普通注释。这样的注释使行非空。
块注释与之前或之后的代码缩进相同，他们可能是 /* ... */风格或 // ...风格， 多行注释 /* ... */ 后面的*必须与前一行的*对齐。
/*
* This is // And so /* Or you can
* okay. // is this. * even do this. */
*/
注释不包含用在星号或其他字符绘制框中。
小贴士：在多行注释，如果希望自动代码格式化注释内容请使用 /* ... */，大多数格式化不会格式化 // ... 中的内容。
类和成员修饰度按Java语言规范建议顺序显示：
public protected private abstract default static final transient volatile synchronized native strictfp
long数值使用大写 L 后缀从不使用小写（避免与数字1混淆）例如： 3000000000L 而不是3000000000l
5. 命名规范
标识符仅使用ASCII字母和数字，并在少数情况下使用下划线。因此每个有效的标识符名称都符合正则表达式\w+。
在Google风格中不使用特殊的前缀或后缀。例如这些名称不是Google风格：name_ mName s_name 和 kName。
包名都是小写的，练习的单词连在一起（没有下划线）。例如：com.example.deepspace, 而不是 com.example.deepSpace 或 com.example.deep_space
类名符合大写驼峰式写法。
类名通常是名词或名词短语，例如： Character 或 ImmutableList 。接口名也可能是名词或名词短语 （例如： List）。但有时可能是形容词或者形容词短语（例如： Readable）。
注解类型没有特定命名规则，或完整的约定。
测试类的名字是以Test结尾的名字，包含测试的内容。例如 HashTest 或 HashIntegrationTest
类名符合小写驼峰式写法。
方法名通常是动词或动词短语。例如 sendMessage 或 stop。
下划线可能出现在JUnit测试方法名称中，用于分隔逻辑组件的名称，每个组件都符合小写驼峰式写法。 一种典型的模式是 <methodUnderTest>_<state> 例如：pop_emptyStack。测试方法没有典型的命名方法。
常量名通常使用CONSTANT_CASE：全大写字母，单词之间以下划线风格。但是什么是常数？
常量是static final定义的字段，其内容是不可变更的，其方法没有可以检测的方式。这包括基础类型、字符串、 不可变类型和不可变类型的不可变集合。如果实例包括任何可检测的更改，则它不是常量。仅仅打算永远不改变对象是不够的。 例如：
// 常量
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
// 非常量
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 ImmutableMap<String, SomeMutableType> mutableValues =
ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};
这些名字通常是名词或名词短语。
非静态字段名（静态或其他）命名参考小写驼峰式写法
这些名字通常名词或名词短语。例如： computedValues 或 index
参数名命名参考小写驼峰式写法
应避免使用公共方法中的单字符参数名称。
局部变量名命名参考小写驼峰式写法
即使局部变量定义为final和不可变，也不认为是常量，并且不应该设置为常量。
每个类型变量都是以下两种样式之一：
- 单个大写字母，后面可能包含单个数字（例如
E T X T2）
- 用于类名的方式（参见第5.2.2节 类名）后跟大写字母T（例如：
RequestT FooBarT）
5.3. 驼峰式命名：定义
有时英语短语转换为大小写驼峰的方法不止一种。即当首字母为缩略词或 等不寻常结构时。为了提高可预测性， Google风格指定以下机种（几乎）确定性方案。
从以下名词方式开始：
- 将短语转换为纯ASCII字符并删除任何引号。例如："Müller's algorithm" 写为"Muellers algorithm"。
- 将此结果划分为单词，拆分空格和任何其他标点（通常为连字符）。
- 建议：如果任何单词已经具有常规使用的传统驼峰式外观，请将其拆为两部分（例如："AdWords" 变为 "ad words"） 请注意，诸如iOS之类单词本身不是真正的驼峰，因此该建议不适用。
- 小写内容（包含首字母缩略词）只需要首字母大写：
- ... 每个词适用大写驼峰式，或
- ... 每个词除了第一个使用小写驼峰式
- 最后将所有单词拼成一个标识符。
请注意原始单词大小写几乎完全被忽略。例如：
| Prose form |
Correct |
Incorrect |
| "XML HTTP request" |
XmlHttpRequest |
XMLHTTPRequest |
| "new customer ID" |
newCustomerId |
newCustomerID |
| "inner stopwatch" |
innerStopwatch |
innerStopWatch |
| "supports IPv6 on iOS?" |
supportsIpv6OnIos |
supportsIPv6OnIOS |
| "YouTube importer" |
YouTubeImporter <br> YoutubeImporter[1] |
|
[1] 可接受，但不推荐
注意：有些单词在英语中含糊不清：例如 "nonempty" 和 "non-empty" 都是正确的。因为方法名 checkNonempty 和 checkNonEmpty 都是正确的。
6. 编程实战
6.1. @Override：永远适用
方法使用 @Override 注解时。这包括覆盖父类方法、实现接口方法以及覆盖父类接口方法。
例外：当父方法为@Deprecated时，可能省略@Override。
6.2. 捕获异常：不忽略
除非如如下所述，否则应对捕获异常时不执行任何操作。（典型响应是纪录这个问题，或者认为它是"不可能"的并重新抛出 AssertionError。）
如果不在捕获去不采用任何行为，那个合理的原因是在注释中解释。
try {
int i = Integer.parseInt(response);
return handleNumericResponse(i);
} catch (NumberFormatException ok) {
// it's not numeric; that's fine, just continue
}
return handleTextResponse(response);
例外：在测试中，如果捕获异常名称或开头，可以忽略并不注释。以下是一种常见的习惯用法，确保被测代码确实抛出异常， 因此不需要注释。
try {
emptyStack.pop();
fail();
} catch (NoSuchElementException expected) {
}
6.3. 静态成员：使用class限定
当必须限定对静态成员引用时，它将使用类名限定，而不是使用该类类型的应用或表达式限定。
Foo aFoo = ...;
Foo.aStaticMethod(); // 好
aFoo.aStaticMethod(); // 差
somethingThatYieldsAFoo().aStaticMethod(); // 非常差
6.4. Finalizers：不使用
覆盖极为罕见的Object.finalize。
小贴士：不要使用这个。如果你必须这样做情先仔细阅读并理解《Effective Java Item 7》，“避免最终完结”然后不要这样做。
7. Javadoc
Javadoc块的基本格式如下：
/**
* Multiple lines of Javadoc text are written here,
* wrapped normally...
*/
public int method(String p1) { ... }
或者单行示例：
/** An especially short bit of Javadoc. */
基本格式是可以接受的。当整个Javadoc块（包括注释标记）可以放到单行时，可以替换单行形式。请注意这仅适用于没有 @return 等标记的情况。
一个空白行——即只包含对齐的前星号（*）的行——出现在段落之间，以及标记组之前（如果存在）。 第一个段落在<p>之后，后面没有空格。
任何标准的块标记都以 @param @return @throws @deprecated 的顺序出现，并且这四种类型永远不会出现空描述。 当表示不适合单行时，连续行将从@位置缩进4个（或更多）空格。
每个Javadoc块都以简短的摘要片段开头。这片段很重要：它是文本中唯一出现在某些上下文的部分。例如类和方法索引。
这是一个片段——一个名词短语或动词短语，而不是完整的句子。它不是 A {@code Foo} is a... 或 This method returns...，也不会像保存纪录那种构成一个完整的句子。然而这些片段都是大写的，好像是一条完整的句子。
小贴士：一个常见的错误是以 /** @return the customer ID */ 的形式组成的简单Javadoc。 这是不正确的，应该改成 /** Returns the customer ID. */。
7.3. 在哪使用Javadoc
至少，Javadoc适用 public 类以及每个的 public 或 protected 成员类。下面列出一些额外情况。
如第7.3.4节非必须Javadoc中所述，这可能存在其他Javadoc内容。
Javadoc对于像 getFoo 这样的“简单，明显”的方法是可选的，在这种情况下除了 Returns the foo 之外没什么可以解释的。
重要提示：引用此例外的证明省略典型读者需要相关信息是不合适的。例如，对于名为getCanonicalName的方法，如果典型读者可能不知道“术语规范”，请不要省略文档（其理由为/** Returns the canonical name. */）。
Javadoc并不总是出现在覆盖父类型方法。
其他类和成员需要或者期望有Javadoc
每当实现注释用于定义类或成员体目或行为时，注释使用Javadoc方式（使用/**）
不要求非必须的Javadoc遵循第7.1.2节、第7.1.3节和第7.2节格式规则，但当然建议使用。
