Google Java 风格指南(Google Java Style Guide)

注：文章由于在博客园上阅读页面带点卡顿，所以在此发了一下，可能是由于我在博客园的博客自定义设置影响整体页面的加载。

官方地址 google.github.io

本文档作为 Google 的 Java™ 编程语言源代码编码标准的完整定义。当且仅当它遵守此处的规则时，Java 源文件才被描述为 Google 风格。

前言

声明：在原文挡基础上做了一次翻译并总结了一下具体内容，换了一下排版样式等等。

在此也参考了另外一篇已经有很长时间的翻译版：https://hawstein.com/2014/01/20/google-java-style/

要提一点的是，国内的话可能更熟悉阿里的开发手册📎Java开发手册（嵩山版）.pdf或者《Effective Java》
（Gitee：https://gitee.com/lin-mt/effective-java-third-edition
在线网阅读的一个网站:https://www.mianshigee.com/tutorial/effective-java-3rd-chinese/docs-readme.md ）

所以Google的开发规范可能不怎么熟悉，甚至和我一样有点感觉不习惯。毕竟只是一种形式而已，不能说用了Google规范，就可以进谷歌，甚至代码更流畅，只能说，相互参照一些内容，可以让代码更方便阅读以及维护吧。

（不过，个人可能还是习惯了国内的阿里，Effective java 这本书还没有看完，唉，还是太懒了）

---

一、简介

本文档作为 Google 的 Java™ 编程语言源代码编码标准的**完整定义。**当且仅当它遵守此处的规则时，Java 源文件才被描述为 Google 风格。

与其它的编程风格指南一样，这里所讨论的不仅仅是编码格式美不美观的问题， 同时也讨论一些约定及编码标准。然而，这份文档主要侧重于我们所普遍遵循的规则， 对于那些不是明确强制要求的，我们尽量避免提供意见。

1.1 术语说明

在本文件中，除非另有说明：

1. 术语 *class* 包含地用于表示 “普通” 类、枚举类、接口或注解类型 ( @interface)。
2. 术语成员（of a class）包含性地用于表示嵌套的类、字段、方法或构造函数；也就是说，除了初始化程序和注释之外的类的所有顶级内容。
3. 术语comment只用来指代实现的注释(implementation comments)，我们不使用“documentation comments”一词，而是用Javadoc。

1.2 指导说明

本文档中的示例代码是非规范的。也就是说，虽然这些示例采用 Google 风格，但它们可能无法说明表示代码的唯一***时尚方式。示例中的可选格式选择不应作为规则强制执行*。（不强制你使用这种规范）

---

二、源文件基础

2.1 文件名

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

2.2 文件编码：UTF-8

源文件以 UTF-8 编码。

2.3 特殊字符

2.3.1 空白字符

除了行终止符序列之外，ASCII 水平空格字符 ( 0x20 ) 是唯一出现在源文件中任何位置的空白字符。这意味着：

1. 字符串和字符文字中的所有其他空白字符都被转义。
2. 制表符不用于缩进。

2.3.2 特殊转义序列

对于任何具有 特殊转义序列 （\b、 \t、 \n、 \f、 \r、 和 ）的字符\"， 将使用该序列而不是相应的八进制（例如 ）或 Unicode（例如 ）转义。\'``\\``\012``\u000a

2.3.3 非 ASCII 字符

对于剩余的非 ASCII 字符，使用实际的 Unicode 字符（例如 ∞）或等效的 Unicode 转义 符（例如 ） \u221。选择仅取决于使代码更易于阅读和理解的方式，尽管强烈建议不要使用 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字符而让你的代码可读性变差。当程序无法正确处理非ASCII字符时，它自然无法正确运行， 你就会去fix这些问题的了。(言下之意就是大胆去用非ASCII字符，如果真的有需要的话)

---

三、源文件结构

源文件按顺序包括：

1. 许可或版权信息（如果需要）
2. 包装声明（package语句）
3. 导入语句（import语句）
4. 一个顶级类(只有一个)

恰好一个空行分隔存在的每个部分（以上每个部分之间用一个空行隔开）。

3.1 许可或版权信息（如果需要）

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

3.2 包装声明（package语句）

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

3.3 导入语句（import语句）

3.3.1 import不要使用通配符

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

3.3.2 无换行

import语句不换行，列限制(4.4节，列限制：100)并不适用于import语句。(每个import语句独立成行)

3.3.3 排序和间距

import的顺序如下。

1. 所有的静态导入在一个区块中。

2. 所有非静态进口在一个区块中。

如果同时有静态和非静态的导入，则用一个空行来分隔这两个块。在导入语句之间没有其他空行。

在每个区块中，导入的名字以ASCII排序方式出现。(注意：这与导入语句的ASCII排序不同，因为’.‘排序在’；'之前）

3.3.4 没有静态导入的类

静态导入不用于静态嵌套类。它们是用普通的导入方式导入的。

关于静态导入可参考这篇文章：https://www.cnblogs.com/mengdd/archive/2013/01/23/2873312.html

百度知道 解释：

3.4 类声明

3.4.1 只有一个顶层类的声明

每个顶层类都驻留在一个自己的源文件中。

3.4.2 类内容的排序

你为你的类的成员和初始化器选择的顺序对可学习性有很大影响。然而，如何做到这一点并没有一个正确的秘诀；不同的类可能会以不同的方式排列其内容。

重要的是，每个类都使用一些逻辑顺序，如果有人问起，其维护者可以解释。例如，新的方法不会被习惯性地添加到类的末尾，因为这将产生 "按添加日期的时间顺序 "排序，而这并不是一个逻辑排序

3.4.2.1 重载：从不拆分

当一个类有多个构造函数或多个同名方法时，这些方法会按顺序出现，中间没有其他代码（甚至没有私有成员）

---

四、格式化

术语说明：类块结构是指类、方法或构造函数的主体。请注意，根据第4.8.3.1节关于数组初始化器的规定，任何数组初始化器都可以选择性地被当作类块结构来处理

4.1 大括号

4.1.1 在可选的地方使用大括号

大括号用于if、else、for、do和while语句，即使主体为空或只包含一条语句``

4.1.2 非空块：K & R 风格

大括号遵循 Ke