空白字符

除了换行符序列之外，ASCII 水平空格字符（0x20）是源文件中任何地方出现的唯一空白字符。这意味着

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

特殊转义序列

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

非 ASCII 字符

对于剩余的非 ASCII 字符，使用实际的 Unicode 字符（例如 ∞）或等效的 Unicode 转义（例如 \u221e），具体取决于哪个使代码更易于阅读和理解。

提示：在 Unicode 转义的情况下，有时甚至在使用实际 Unicode 字符时，解释性注释非常有用。

示例

提示：不要仅仅因为担心某些程序可能无法正确处理非 ASCII 字符而使代码可读性降低。如果发生这种情况，这些程序是损坏的，必须修复。

主树中没有通配符导入

通配符导入（静态或其他）不使用。

测试树中的静态通配符导入

对于测试导入（如 JUnit、EasyMock 和 Hamcrest），鼓励使用通配符静态导入。

不换行

导入语句不换行。列限制（列限制：120）不适用于导入语句。

排序和间距

导入语句分为以下几组，按此顺序排列，每组之间用一个空行隔开

1. java
2. javax
3. org
4. com
5. 所有静态导入都在一个组中

在一个组内没有空行，导入的名称按 ASCII 排序顺序出现。（注意：这与导入语句按 ASCII 排序顺序不同；分号的存在会扭曲结果。）

可以在源代码分发中找到用于自动排序导入的 IDE 设置，位于src/ide下。例如

• Eclipse：src/ide/eclipse/4.3.2/organize-imports.importorder
• IntelliJ：src/ide/Intellij/13/IntellijSettings.jar

正好一个顶级类声明

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

类成员排序

类成员应按以下顺序分组>。

1. 静态变量按以下所示顺序分组。在一个组内，变量可以按任何顺序出现。
2. 1. public
   2. protected
   3. package
   4. private
3. 实例变量按以下所示顺序分组。在一个组内，变量可以按任何顺序出现
4. 1. public
   2. protected
   3. package
   4. private
5. 构造函数
6. 方法可以按以下顺序指定，但如果可以提高程序的清晰度，也可以按其他顺序出现。
7. 1. public
   2. protected
   3. package
   4. private

大括号用于可选的地方

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

非空块：K & R 风格

大括号遵循 Kernighan 和 Ritchie 风格（"埃及括号"）用于非空块和块状结构

• 左大括号前没有换行。
• 左大括号后有换行。
• 右大括号前有换行。
• 右大括号后有换行，如果该大括号终止一个语句或方法、构造函数或命名类的主体。例如，如果大括号后面是else或逗号，则没有换行。

示例

      return new MyClass() {
          @Override public void method() {
              if (condition()) {
                  try {
                      something();
                  } catch (ProblemException e) {
                      recover();
                  }
              }
          }
      };
    

枚举类的一些例外情况在第 4.8.1 节中给出，枚举类。

空块：可以简洁

空块或块状结构可以在打开后立即关闭，中间没有字符或换行（{}），除非它是多块语句的一部分（直接包含多个块：if/else-if/else或try/catch/finally）。

示例

      void doNothing() {}
    

在哪里换行

换行的首要原则：优先在更高的语法级别换行。此外

1. 当在非赋值运算符处换行时，换行符位于符号之前。（请注意，这与 Google 风格中用于其他语言（如 C++ 和 JavaScript）的做法不同。）
   • 这也适用于以下“运算符类”符号：点分隔符（.）、类型边界中的与符号（<T extends Foo & Bar>）以及 catch 块中的管道符（catch (FooException | BarException e)）。
2. 当在赋值运算符处换行时，换行符通常位于符号之后，但两种方式都是可以接受的。
   • 这也适用于增强型for（“foreach”）语句中的“赋值运算符类”冒号。
3. 方法或构造函数名称与其后面的左括号（(）保持在一起。
4. 逗号（,）与其前面的标记保持在一起。

缩进续行至少 +8 个空格

换行时，第一行之后的每一行（每个续行）至少比原始行缩进 +8 个空格。

当有多个续行时，缩进可以根据需要进行调整，超过 +8 个空格。一般来说，如果两个续行以语法上平行的元素开头，则它们使用相同的缩进级别。

水平对齐部分讨论了使用可变数量的空格来将某些标记与前几行对齐的做法，这种做法是不鼓励的。

垂直空白

单个空行出现在

1. 之间类的连续成员（或初始化器）：字段、构造函数、方法、嵌套类、静态初始化器、实例初始化器。
   • 例外：在两个连续的字段之间（它们之间没有其他代码）的空行是可选的。这些空行根据需要使用，以创建字段的逻辑分组。
2. 在方法体中，根据需要创建语句的逻辑分组。
3. 可选地在类的第一个成员之前或最后一个成员之后（既不鼓励也不反对）。
4. 根据本文档其他部分的要求（例如导入语句）。

多个连续的空行是允许的，但从不需要（也不鼓励）。

水平空白

除了语言或其他样式规则要求的地方，以及文字、注释和 Javadoc 之外，单个 ASCII 空格也仅出现在以下位置。

1. 将任何保留字（如if、for或catch）与紧随其后的左括号（(）分隔开
2. 将任何保留字（如else或catch）与紧随其前的右大括号（}）分隔开
3. 在任何左大括号（{）之前，有两个例外
   • String[][] x = {{"foo"}};（根据第 8 项，{{之间不需要空格）
4. 在任何二元或三元运算符的两侧。这也适用于以下“运算符类”符号
   • 连接类型边界中的与符号：<T extends Foo & Bar>
   • 处理多个异常的 catch 块中的管道符：catch (FooException | BarException e)
   • 增强型for（“foreach”）语句中的冒号（:）
5. 在,:;或强制转换的右括号（)）之后
6. 在开始行尾注释的双斜杠（//）的两侧。这里允许使用多个空格，但不需要。
7. 在声明的类型和变量之间：List<String> list
8. 可选地在数组初始化器的两个大括号内
   • new int[] {5, 6}和new int[] { 5, 6 }都是有效的

注意：此规则从不强制要求或禁止在行首或行尾添加额外的空格，只针对内部空格。

水平对齐：从不强制要求

术语说明：水平对齐是指在代码中添加可变数量的额外空格的做法，目的是使某些标记出现在前几行中某些其他标记的正下方。

这种做法是允许的，但Google 风格从不强制要求。即使在已经使用水平对齐的地方，也不需要保持水平对齐。

以下是一个没有对齐的示例，然后是使用对齐的示例

      private int x; // this is fine
      private Color color; // this too

      private int   x;      // permitted, but future edits
      private Color color;  // may leave it unaligned
    

提示：对齐可以提高可读性，但会给未来的维护带来问题。考虑一下将来需要修改单行的更改。这种更改可能会使以前令人愉悦的格式变得混乱，而这是允许的。更常见的情况是，它会促使程序员（可能是你）也调整附近行的空白，可能触发一系列级联的重新格式化。这个单行更改现在有了“爆炸半径”。这在最坏的情况下会导致毫无意义的繁琐工作，但在最好的情况下，它仍然会破坏版本历史信息，减慢审查速度，并加剧合并冲突。

枚举类

在每个枚举常量后面的逗号之后，换行符是可选的。

没有方法且其常量上没有文档的枚举类可以选择性地像数组初始化器一样格式化（参见数组初始化器）。

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

由于枚举类是类，因此所有其他类格式化规则都适用。

变量声明

数组

      new int[] {           new int[] {
        0, 1, 2, 3            0,
      }                       1,
                              2,
      new int[] {             3,
        0, 1,               }
        2, 3
      }                     new int[]
                                {0, 1, 2, 3}
    

switch 语句

术语说明：在switch 块的大括号内是一个或多个语句组。每个语句组由一个或多个switch 标签（case FOO:或default:）组成，后面跟着一个或多个语句。

      switch (input) {
        case 1:
        case 2:
          prepareOneOrTwo();
          // fall through
        case 3:
          handleOneTwoOrThree();
          break;
      default:
          handleLargeNumber(input);
      }
    

注释

应用于类、方法或构造函数的注释出现在文档块之后，每个注释都单独列在一行上（即，每行一个注释）。这些换行符不构成换行（第 4.5 节，换行），因此缩进级别不会增加。示例

      @Override
      @Nullable
      public String getNameIfPresent() { ... }
    

异常： 一个单独的无参数注解可以与签名的第一行一起出现，例如

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

应用于字段的注解也出现在文档块之后，但在这种情况下，多个注解（可能带参数）可以列在同一行上；例如

      @Partial @Mock DataLoader loader;
    

没有关于格式化参数和局部变量注解的特定规则。

注释

      /*
       * This is          // And so           /* Or you can
       * okay.            // is this.          * even do this. */
       */
    

修饰符

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

      public protected private abstract static final transient volatile synchronized native strictfp
    

数值字面量

long 值的整数字面量使用大写L后缀，绝不使用小写（避免与数字1混淆）。例如，3000000000L而不是3000000000l。

包名

包名全部小写，连续的单词简单地连接在一起（没有下划线）。例如，com.example.deepspace，而不是com.example.deepSpace或com.example.deep_space。

类名

类名使用大驼峰命名法编写。

类名通常是名词或名词短语。例如，Character或ImmutableList。接口名也可能是名词或名词短语（例如，List），但有时也可能是形容词或形容词短语（例如，Readable）。

没有关于命名注解类型的特定规则，甚至没有公认的约定。

测试类以它们测试的类的名称开头，以Test结尾。例如，HashTest或HashIntegrationTest。

方法名

方法名使用小驼峰命名法编写。

方法名通常是动词或动词短语。例如，sendMessage或stop。

JUnit 测试方法名中可能出现下划线，以分隔名称的逻辑组件。一种典型的模式是test<MethodUnderTest>_<state>，例如testPop_emptyStack。没有一种正确的方法来命名测试方法。

常量名

常量名使用CONSTANT_CASE：所有字母都大写，单词之间用下划线分隔。但究竟什么是常量呢？

每个常量都是一个静态 final 字段，但并非所有静态 final 字段都是常量。在选择常量命名法之前，请考虑该字段是否真的感觉像一个常量。例如，如果该实例的任何可观察状态可以改变，它几乎肯定不是一个常量。仅仅打算永远不改变对象通常是不够的。示例

      // 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"};
    

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

非常量字段名

非常量字段名（静态或其他）使用小驼峰命名法编写。

这些名称通常是名词或名词短语。例如，computedValues或index。

参数名

参数名使用小驼峰命名法编写。

应避免使用单字符参数名。

局部变量名

局部变量名使用小驼峰命名法编写，并且可以比其他类型的名称更自由地缩写。

但是，应避免使用单字符名称，除非是临时变量和循环变量。

即使是 final 和不可变的，局部变量也不被认为是常量，也不应该像常量那样进行样式化。

类型变量名

每个类型变量都以两种风格之一命名

• 单个大写字母，可选地后跟单个数字（例如E、T、X、T2）
• 以用于类的形式命名的名称（参见类名），后跟大写字母T（示例：RequestT、FooBarT）。

通用形式

Javadoc 块的基本格式如本例所示

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

... 或者在本例中，单行示例

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

基本形式始终是可接受的。当没有 at 子句存在时，可以使用单行形式，并且整个 Javadoc 块（包括注释标记）可以放在一行上。

段落

段落之间以及（如果存在）在“at 子句”组之前出现一行空行——即，仅包含对齐的引导星号（*）的行。除第一个段落之外，每个段落都在第一个单词之前立即出现<p>，后面没有空格。

At 子句

使用的任何标准“at 子句”都按@param、@return、@throws、@deprecated的顺序出现，这四种类型永远不会出现空描述。当 at 子句不能放在一行上时，续行从@的位置缩进四个（或更多）空格。

例外：不言自明的函数

对于像getFoo这样“简单明了”的函数，Javadoc是可选的，因为在这些情况下，除了“返回foo”之外，真的没有其他有价值的内容需要说明。

重要：不要以这个例外为借口省略典型读者可能需要了解的相关信息。例如，对于一个名为getCanonicalName的函数，如果典型读者可能不知道“规范名称”的含义，就不要省略它的文档（理由是它只会说/** 返回规范名称。 */）。

例外：重写

重写超类型方法的函数并不总是包含Javadoc。