Google Java 代码规范

Stella981
• 阅读 563

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 dowhile语句,即使是空或者只有一条语句,也应该使用花括号。

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/elsetry/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 forcatch)从该行后面的开括号(()或行分离出来。
  2. 将任何保留字(elsecatch)与该行之前的花括号(‘}’)分开
  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()
  1. 在(,:;)之后或者关闭符号())之前
  2. 在双斜杠(//)的两侧开始一行结束注释。这里允许多个空格,但不是必须的。
  3. 在声明的类型和变量之间:List<String> list
  4. 在数组的初始化的两个花括号之间可选:
    • new int[] {5, 6}new int[] { 5, 6 } 都是有效的
  5. 在类型注解和[]...之间

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

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_namekName

5.2. 标识符类型规则

5.2.1. 包名

包名都是小写的,练习的单词连在一起(没有下划线)。例如:com.example.deepspace, 而不是 com.example.deepSpacecom.example.deep_space

5.2.2. 类名

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

类名通常是名词或名词短语,例如: CharacterImmutableList 。接口名也可能是名词或名词短语 (例如: List)。但有时可能是形容词或者形容词短语(例如: Readable)。

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

测试类的名字是以Test结尾的名字,包含测试的内容。例如 HashTestHashIntegrationTest

5.2.3. 方法名

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

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

下划线可能出现在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. 非常量字段名

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

这些名字通常名词或名词短语。例如: computedValuesindex

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" 都是正确的。因为方法名 checkNonemptycheckNonEmpty 都是正确的。

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 类以及每个的 publicprotected 成员类。下面列出一些额外情况。

如第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节格式规则,但当然建议使用。

点赞
收藏
评论区
推荐文章
Jacquelyn38 Jacquelyn38
1年前
2020年前端实用代码段,为你的工作保驾护航
有空的时候,自己总结了几个代码段,在开发中也经常使用,谢谢。 1、使用解构获取json数据let jsonData   id: 1, status: "OK", data: ['a', 'b'] ; let  id, status, data: number   jsonData; console.log(id, status, number )
刚刚好 刚刚好
2个月前
css问题
1、 在IOS中图片不显示(给图片加了圆角或者img没有父级) <div<img src""/</div div {width: 20px; height: 20px; borderradius: 20px; overflow: h
blmius blmius
1年前
MySQL:[Err] 1292 - Incorrect datetime value: ‘0000-00-00 00:00:00‘ for column ‘CREATE_TIME‘ at row 1
文章目录 问题 用navicat导入数据时,报错: 原因这是因为当前的MySQL不支持datetime为0的情况。 解决修改sql\mode: sql\mode:SQL Mode定义了MySQL应支持的SQL语法、数据校验等,这样可以更容易地在不同的环境中使用MySQL。 全局s
小森森 小森森
2个月前
校园表白墙微信小程序V1.0 SayLove -基于微信云开发-一键快速搭建,开箱即用
后续会继续更新,敬请期待2.0全新版本 欢迎添加左边的微信一起探讨!项目地址:](https://www.aliyun.com/activity/daily/bestoffer?userCodesskuuw5n) \2. Bug修复更新日历 2. 情侣脸功能大家不要使用了,现在阿里云的接口已经要收费了(土豪请随意), \ \ 和 注意
艾木酱 艾木酱
1个月前
快速入门|使用MemFire Cloud构建React Native应用程序
> MemFire Cloud是一款提供云数据库,用户可以创建云数据库,并对数据库进行管理,还可以对数据库进行备份操作。它还提供后端即服务,用户可以在1分钟内新建一个应用,使用自动生成的API和SDK,访问云数据库、对象存储、用户认证与授权等功能,可专
Stella981 Stella981
1年前
KVM调整cpu和内存
一.修改kvm虚拟机的配置 1、virsh edit centos7 找到“memory”和“vcpu”标签,将 <name>centos7</name> <uuid>2220a6d1-a36a-4fbb-8523-e078b3dfe795</uuid>
Wesley13 Wesley13
1年前
MySQL查询按照指定规则排序
1.按照指定(单个)字段排序 select * from table_name order id desc; 2.按照指定(多个)字段排序 select * from table_name order id desc,status desc; 3.按照指定字段和规则排序 selec
Stella981 Stella981
1年前
Angular material mat
Icon Icon Name mat-icon code _add\_comment_ add comment icon <mat-icon> add\_comment</mat-icon> _attach\_file_ attach file icon <mat-icon> attach\_file</mat-icon> _attach\
Wesley13 Wesley13
1年前
MySQL部分从库上面因为大量的临时表tmp_table造成慢查询
#### 背景描述 # Time: 2019-01-24T00:08:14.705724+08:00 # User@Host: **[**] @ [**] Id: ** # Schema: sentrymeta Last_errno: 0 Killed: 0 # Query_time: 0.315758 Lock_
helloworld_28799839 helloworld_28799839
2个月前
常用知识整理
# Javascript ## 判断对象是否为空 ```js Object.keys(myObject).length === 0 ``` ## 经常使用的三元运算 > 我们经常遇到处理表格列状态字段如 `status` 的时候可以用到 ``` vue
helloworld_34035044 helloworld_34035044
4个月前
皕杰报表之UUID
​在我们用皕杰报表工具设计填报报表时,如何在新增行里自动增加id呢?能新增整数排序id吗?目前可以在新增行里自动增加id,但只能用uuid函数增加UUID编码,不能新增整数排序id。 uuid函数说明:获取一个UUID,可以在填报表中用来创建数据ID语法:uuid() 或 uuid(sep)参数说明:sep 布尔值,生成的uuid中是否包含分隔符'',缺省为