1. 简介

本文档用于Java编程语言的Google源代码编码标准的完整定义。Java源文件定义为Google风格。

于其他编程风格指南一样，所涉及的问题不止包含代码格式美化，还包括其他类型的约定或者编码标准。 但是本文档主要关注普遍遵循的严格规则，并避免提供意义不明的可执行建议（无论任何方式）。

1.1. 术语说明

本文件中除非另有说明：

1. class包含用于表示普通类、枚举、接口或注解类型（@interface）
2. 成员用于表示嵌套类、字段、方法或构造方法，也就是说除了初始设定和注释的顶级内容
3. 注释总是实现注释，我们不使用短语“文档注释”，而是使用常规术语javadoc

其他术语说明会在整个文件中偶尔出现

译者注：嵌套类即内部类

1.2. 规范说明

本文档中的示例代码是非规范的。也就是说虽然示例是Google风格，但它们可能没有说明代码的唯一方式。 示例中的可选格式也不应作为规则强制执行。

2. 源文件基础

2.1. 文件名

源文件名包含顶级类并区分大小写（并且只有一个），加上.java扩展名。

2.2. 文件编码

源码文件编码必须是 UTF-8

译者注：因为不同操作系统默认的换行符不一样，请统一使用\n(LF)作为代码换行符。

2.3. 特别字符

2.3.1. 空白字符

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

1. 字符串和字符文字中的其他空格字符都被转义
2. 制表符(0x09)不可以用于缩紧

2.3.2. 特别字符序列

任何字符包含特别字符序列（\b \t \n \f \r \" \'和 \\），使用该序列不应该转成八进制或Unicode转义。

2.3.3. 非ASCII字符

对于其他非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. 源码结构

源文件顺序包括：

1. 许可证或版权许可（如果有）
2. Package声明
3. Import语句
4. 恰好一个顶级类

恰好一个空白行将每个部分区分开

译者注：请在顶级类之前加入必要的文档注释，并包含作者信息。

3.1. 许可证或版权讯息

如果许可或者版权信息术语文件，这放在这里

译者注：许可信息通常包含两部分，完整许可文件和版权信息（Copyright段落）。 完整文件请放在项目根目录下，代码仅包含版权信息。

3.2. Package语句

Package语句是不换行的。列限定（第4.4节，列限制：100）不用于包语句。

3.3. Import语句

3.3.1. 没有通配符导入

通配符导入，静态或普通类都不能使用。

3.3.2. 不换行

Import语句是不换行的。列限定（第4.4节，列限制：100）不用于导入语句。

3.3.3. 次序间隔

导入次序如下：

1. 所有静态导入独立一行。
2. 所有非静态导入独立一行。

如果同时包含静态和非静态导入，一个空白行将两块分开，导入语句之间不包含任何空白行。

在每个快中，导入名称以ASCII排序显示。（注意：这与ASCII排序的import语句不同，因为.在;之前排序。）

3.3.4. 非静态类导入

静态导入不用于静态嵌套类，他们是通过正常导入的方式导入的。

3.4. 类定义

3.4.1. 恰好一个顶级类定义

每一个源文件只能拥有一个顶级类

3.4.2. 类内容次序

你选择成员和初始化的顺序可能会对学习造成很大的影响，但是没有一个正确的方法可以做到这一点， 不懂类可以有不同的方式排序内容。

重要的是每个类使用的逻辑顺序一样，如果被问到维护者可以解释它。例如新方法被习惯性的加到末尾。 因为这将产生“按时间顺序添加”排序，这不是逻辑排序。

4. 格式化

术语注意：块结构是指类、方法或者构造方法的主体。请注意，通过关于数组初始化定义在4.8.3.1， 可以选择将任何数组设定项视为类似块的结构。

4.1. 花括号

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

花括在在使用if else for do 和 while语句，即使是空或者只有一条语句，也应该使用花括号。

4.1.2. 非空块：K&R样式

对于非空块和类块接口，花括号遵循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节列出

4.1.3. 空块：可能很简洁

空块或者类块接口可以采用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样式）

4.3. 每行一句声明

每条语句后面都有一个换行符。

4.4. 列限制：100

Java代码的列限制为100个字符。字符表示任何Unicode码。除非另有说明，否则任何超出此限制都必须换行， 如4.5节“换行”所述。

每一个Unicode码为一个字符，即使显示宽度大于或者小于。如果使用全角字符， 你可以选择比此规则严格要求更早的位置换行。

译者注：请使用等宽字体，另不建议在代码中使用Unicode（即ASCII以外的字符）。

例外：

1. 不遵守列限制的行（例如Javadoc中的长URL或长JSNI方法引用）
2. package和import语句（参见3.2.Package语句和3.3.Import语句）
3. 注释中的命令行可以剪切-黏贴到shell中

4.5. 换行

术语注意：当可能合法占用单行的代码为多行时，此活动会杭杭。

没有全面的，确定性的公式显示如何在不同情况下换行，通常有机种有效的方法来包装同一段代码。

注意：虽然换行典型原因是为了避免溢出列限制，但即使实际符合列限制的代码也可能由作者自行决定是否换行

小贴士：提取方法或者局部变量可以解决问题而无需换行

4.5.1. 在哪断开

换行的主要原因是更喜欢在更高的语句断开。

1. 当非复值运算符在断行时，断点出现在符号之前。（请注意，这与C++和Javascript在Google风格中使用的作法不同）
   • 这也适用与以下“操作类似”的符号
     • 点符（.）
     • 方法参考的两个冒号（::）
     • 类型绑定符号（<T extends Foo & Bar>）
     • 捕获块中的管道（catch (FooException | BarException e)）
2. 当复值运算符在断行处执行时，断点通常出现在符号之后，但是任何一种方式都是可接受的
   • 这也适用于增强性for（“foreach”）语句中的复值操作符
3. 方法或构造方法名称后面的左括号（(）的后面
4. 逗号（,）的后面
5. 在Lambda中的箭头旁边的符号永远不会破坏，除非Lambda的主体由单个无支撑表达式组成。则箭头后面可能出现断点。

例如：

MyLambda<String, Long, Object> lambda =
    (String label, Long value, Object obj) -> {
        ...
    };

Predicate<String> predicate = str ->
    longExpressionInvolving(str);

注意：换行的主要目的是表达清晰的代码，而不一定适合最小行数的代码

4.5.2. 缩紧延续至少+4个空格

换行时，第一行之后每行从原始缩紧至少+4

当存在多个连续行的时候，根据需要压缩可以变化超过+4。通常当且仅当以行元素开始头时，两个连续行使用相同的缩紧级别。

关于水平对齐在4.6.3节解决可变数量空格与前一行对齐。

4.6. 空格

4.6.1. 垂直空格

一个单空白行总是出现：

1. 在类的连续成员或初始值之间：字段，构造方法，方法，嵌套类，静态初始化和实例初始设定项
   • 例外：一个空白行在两个连续字段之间（它们之间没有代码）是可选的。根据需要使用这样的空白行来 创建字段的逻辑分组
   • 例外：枚举常量之间的空白行在4.8.1节中介绍
2. 根据本文档其他部分要求（例如第3节 源文件结构和第3.3节 import语句）

单个空白行也可以出现任何提高可读性的地方，例如在代码组织或者逻辑子部分的语句之间。 第一个成员或者初始化程序之前，或在该类的最后一个成员或初始化程序之后的空白行是不鼓励的。

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

4.6.2. 水平空格

除了语言或其他样式规则要求以外，除了文字、注释和javadoc之外，单个ASCII空间也仅出现以下位置

1. 将任何保留字（if for 或 catch）从该行后面的开括号（(）或行分离出来。
2. 将任何保留字（else 或 catch）与该行之前的花括号（‘}’）分开
3. 在开括号之前，有两点以外：
   • @SomeAnnotation({a, b}) 没有使用空格
   • String[][] x = {{"foo"}}; 没有空格必须在 {{ 之间，参考下面第8项
4. 在任何二元或三元运算符的两边，也适用以下"类似运算符"的符号：
   • 联合类型中&符号： <T extends Foo & Bar>
   • 用于处理多个异常的catch块管道：catch (FooException | BarException e)
   • 增强性for（“foreach”）中的冒号（:）
   • Lambda表达式中的箭头：(String str) -> str.length()

但是请不要：

• 他是方法定义引用俩个冒号（::），类似于Object::toString
• 点分隔符（.）写成object.toString()

5. 在（,:;）之后或者关闭符号（)）之前
6. 在双斜杠（//）的两侧开始一行结束注释。这里允许多个空格，但不是必须的。
7. 在声明的类型和变量之间：List<String> list
8. 在数组的初始化的两个花括号之间可选：
   • new int[] {5, 6} 和 new int[] { 5, 6 } 都是有效的
9. 在类型注解和[]或...之间

该规则从未被解释为在开头或结尾处要求或禁止以外的空间，它只涉及内部空间。

4.6.3. 水平对齐：从不需要

术语注意：水平对齐是在代码中添加可变数量的额外空格的作法，目的是是某些标记直接出现在前一行某些标记的下面。

这种做法是允许的，但是Google风格不需要这种做法。甚至不需要在已经使用过的地方保持水平对齐。

这是一个没有使用对齐的示例，然后使用对齐：

private int x; // 这个还好
private Color color; // 这个一样

private int   x;      // 允许但是后面的内容
private Color color;  // 可能会变得不对齐

小贴纸：对齐可以提高可读性，但是也为将来的维护带来问题。考虑一下以后的代码变化。 这种改变可能会是以前令人愉悦的代码格式化变得严重，并且这是允许的。更常见的是他会提示调整附近的空格， 这可能引起一系列的重新格式化。这种单线改变具有“爆炸半径”。这可能导致无意义的工作，但是他会破坏历史信息， 影响代码审查，并加重冲突。

4.7. 分号括号：推荐

只有当作者和审查者同意没有合理的机会将代码误解为错误，才会省略可选分组括号，也不会使代码更容易阅读。 假设每个读者都记住整个Java运算符优先级是不合理的。

4.8. 特殊字符

4.8.1. 枚举类

在枚举常量后面的每个逗号后，换行符是可选的。还允许额外的空白（通常只有一行）。或许以下这样：

private enum Answer {
  YES {
    @Override public String toString() {
      return "yes";
    }
  },

  NO,
  MAYBE
}

没有方法且没有关于常量的枚举类是可选格式化的，就好像他是一个数组初始化一样（参考数组初始化第4.8.3.1节）

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

由于枚举类是类，因此也适用于格式化格式化类的其他规则。

4.8.2. 变量声明

4.8.2.1. 每个声明一个变量

每个变量声明（字段或内部）只声明一个变量：如 int a, b; 不使用。

例外：for循环的标头中可接受多个变量声明。

4.8.2.2. 需要时声明

局部变量在包含块或者类块构造的开始不声明。局部变量被声明为接近他们首次使用的点（在合理范围内）， 以最小化他们的范围。局部变量声明通常具有初始化代码，或在声明时候立即初始化。

4.8.3. 数组

4.8.3.1. 数组初始化：可以是“类块”

任何数组初始化可以选择格式化，就像它是“块状结构”一样。例如立下都是有效的（不是详细的列表）：

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

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 或抛出异常），要么用注释标记， 表示会进入到下一个语句组。任何说明Fall-through的注释都是必要的（通常用//）。 在switch块的最后一条语句组不需要这种注释。例如：

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

注意，在case 1:之后不需要注释，仅在语句组末尾。

4.8.4.3. default情况的是必须的

每个switch语句都包含default语句组，即使后面没有代码。

例外：enum类型的switch块是可以忽略default语句组的。如果他包含该类型的所有可能值的情况。 这能让IDE或其他静态分析工具提交任何错过的问题。

4.8.5. 注解

注解作用与类、方法、或构造方法的文档注释块之后，并且每个注解都在对应的行上（即每行一个注解）。 这些换行不影响本身的缩进（第4.5节 换行）。

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

例外：单个无参数注释可以与声明第一行一起出现，例如：

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

用于字段的注解也可以在文档注释后出现，但在这种情况下，可能会一起列出多个注解（可能包含参数）；例如：

@Partial @Mock DataLoader loader;

在参数、局部变量或类型上注解没有特定规则格式化。

译者注：为了方便阅读 请不要把注解和方法或变量声明放到同一行，仅当变量为方法的参数的时候放在同一行。

4.8.6. 注释

本节介绍普通注释，javadoc的文档注释会在第7节说到。

任何断行之前可能包含多个空格，后面是普通注释。这样的注释使行非空。

4.8.6.1. 块注释风格

块注释与之前或之后的代码缩进相同，他们可能是 /* ... */风格或 // ...风格， 多行注释 /* ... */ 后面的*必须与前一行的*对齐。

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

注释不包含用在星号或其他字符绘制框中。

小贴士：在多行注释，如果希望自动代码格式化注释内容请使用 /* ... */，大多数格式化不会格式化 // ... 中的内容。

4.8.7. 修饰符

类和成员修饰度按Java语言规范建议顺序显示：

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

4.8.8. 数字标注

long数值使用大写 L 后缀从不使用小写（避免与数字1混淆）例如： 3000000000L 而不是3000000000l

5. 命名规范

5.1. 通用标识规则

标识符仅使用ASCII字母和数字，并在少数情况下使用下划线。因此每个有效的标识符名称都符合正则表达式\w+。

在Google风格中不使用特殊的前缀或后缀。例如这些名称不是Google风格：name_ mName s_name 和 kName。

5.2. 标识符类型规则

5.2.1. 包名

包名都是小写的，练习的单词连在一起（没有下划线）。例如：com.example.deepspace, 而不是 com.example.deepSpace 或 com.example.deep_space

5.2.2. 类名

类名符合大写驼峰式写法。

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

注解类型没有特定命名规则，或完整的约定。

测试类的名字是以Test结尾的名字，包含测试的内容。例如 HashTest 或 HashIntegrationTest

5.2.3. 方法名

类名符合小写驼峰式写法。

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

下划线可能出现在JUnit测试方法名称中，用于分隔逻辑组件的名称，每个组件都符合小写驼峰式写法。 一种典型的模式是 <methodUnderTest>_<state> 例如：pop_emptyStack。测试方法没有典型的命名方法。

5.2.4. 常量名

常量名通常使用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"};

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

5.2.5. 非常量字段名

非静态字段名（静态或其他）命名参考小写驼峰式写法

这些名字通常名词或名词短语。例如： computedValues 或 index

5.2.6. 参数名

参数名命名参考小写驼峰式写法

应避免使用公共方法中的单字符参数名称。

5.2.7. 局部变量名

局部变量名命名参考小写驼峰式写法

即使局部变量定义为final和不可变，也不认为是常量，并且不应该设置为常量。

5.2.8. 类型变量名

每个类型变量都是以下两种样式之一：

• 单个大写字母，后面可能包含单个数字（例如 E T X T2）
• 用于类名的方式（参见第5.2.2节 类名）后跟大写字母T（例如： RequestT FooBarT）

5.3. 驼峰式命名：定义

有时英语短语转换为大小写驼峰的方法不止一种。即当首字母为缩略词或 等不寻常结构时。为了提高可预测性， Google风格指定以下机种（几乎）确定性方案。

从以下名词方式开始：

1. 将短语转换为纯ASCII字符并删除任何引号。例如："Müller's algorithm" 写为"Muellers algorithm"。
2. 将此结果划分为单词，拆分空格和任何其他标点（通常为连字符）。
   • _建议_：如果任何单词已经具有常规使用的传统驼峰式外观，请将其拆为两部分（例如："AdWords" 变为 "ad words"） 请注意，诸如iOS之类单词本身不是真正的驼峰，因此该建议不适用。
3. 小写内容（包含首字母缩略词）只需要首字母大写：
   • ... 每个词适用大写驼峰式，或
   • ... 每个词除了第一个使用小写驼峰式
4. 最后将所有单词拼成一个标识符。

请注意原始单词大小写几乎完全被忽略。例如：

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
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

7.1. 格式化

7.1.1. 通用形式

Javadoc块的基本格式如下：

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

或者单行示例：

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

基本格式是可以接受的。当整个Javadoc块（包括注释标记）可以放到单行时，可以替换单行形式。请注意这仅适用于没有 @return 等标记的情况。

7.1.2. 段落

一个空白行——即只包含对齐的前星号（*）的行——出现在段落之间，以及标记组之前（如果存在）。 第一个段落在<p>之后，后面没有空格。

7.1.3. 块标记

任何标准的块标记都以 @param @return @throws @deprecated 的顺序出现，并且这四种类型永远不会出现空描述。 当表示不适合单行时，连续行将从@位置缩进4个（或更多）空格。

7.2. 摘要片段

每个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内容。

7.3.1. 例外：自解释方法

Javadoc对于像 getFoo 这样的“简单，明显”的方法是可选的，在这种情况下除了 Returns the foo 之外没什么可以解释的。

重要提示：引用此例外的证明省略典型读者需要相关信息是不合适的。例如，对于名为getCanonicalName的方法，如果典型读者可能不知道“术语规范”，请不要省略文档（其理由为/** Returns the canonical name. */）。

7.3.2. 例外：覆盖

Javadoc并不总是出现在覆盖父类型方法。

7.3.2. 非必须Javadoc

其他类和成员需要或者期望有Javadoc

每当实现注释用于定义类或成员体目或行为时，注释使用Javadoc方式（使用/**）

不要求非必须的Javadoc遵循第7.1.2节、第7.1.3节和第7.2节格式规则，但当然建议使用。