Clever Geek Handbook

Google的Java代码格式指南

图片

1.简介



本文档介绍了Google使用Java编程语言进行编码的标准。仅当Java源代码符合本文档中描述的所有规则时，才认为它们符合这些标准。



本教程涵盖的主题不仅涉及代码格式化的美观方面，还涉及其他类型的编码约定或标准。但是，本文档主要集中于定义我们到处都遵循的严格规则，并且没有提供可能被错误实施的建议（无论是人为还是机床）。



1.1术语



在本指南中，定义了以下术语：



  1. 术语类用于表示“常规”类，枚举，接口或注释类型（@interface）
  2. 的术语类构件用于指一个嵌套类，字段，方法或构造，即，对所有高层次的类成员除了初始化块和评论。
  3. 术语注释始终指实施注释。我们不使用“文档注释”一词，而是使用“ Javadoc”一词


本手册中将根据需要提供其余术语。



1.2指导说明



本文档中的代码示例尽管在我们的教程中使用过，但并未展示出唯一正确的格式化方式。



2.源文件。基础



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，\“，\'和\\），最好使用它而不是其对应的八进制值（例如\ 012） ）或Unicode代码（例如\ u000a）。



2.3.3非ASCII字符



对于非ASCII字符，请使用Unicode字符（例如∞）或等效的转义序列（例如\ u221e）。选择这些符号的目的是使代码更易于理解和可读。



在Unicode编码中使用转义字符时，以及在使用有效Unicode字符的情况下，我们强烈建议在此类代码中附上解释性注释。


例 注意
字符串unitAbbrev =“μs” 优秀：即使没有评论也能完美感知
字符串unitAbbrev =“ \ u03bcs” //“μs” 允许，但没有理由这样做
String unitAbbrev =“ \ u03bcs” //希腊字母mu，“ s” 允许但很尴尬，可能导致错误
字符串unitAbbrev =“ \ u03bcs” 不好：读者不知道它是什么
返回'\ ufeff'+ content //字节顺序符号 很好：对非可打印字符使用转义并根据需要添加注释


不要因为担心某些程序将无法正确处理非ASCII字符而使代码的可读性降低。如果发生这种情况，则此类程序将无法正常运行，需要进行修复。


3.源文件结构



源文件由以下元素组成（按显示的顺序）：



  1. 许可或版权信息（如果适用）
  2. 包裹申报
  3. 申报进口
  4. 类声明


正好有一个空白行分隔每个存在的部分。



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



许可或版权信息必须包含在其所引用的文件中。



3.2包装声明



声明的包没有换行符。行宽限制（第4.4节）不适用于包声明。



3.3进口申报



3.3.1导入声明中的通配符



声明导入（静态或非静态）时不使用*（通配符）字符。



3.3.2换行符



声明的导入没有换行符。它们不受线宽限制。



3.3.3排序和间距



导入顺序如下：



  1. 所有静态导入都放置并分组在一个块中
  2. 所有非静态导入都放置在另一个块中


如果同时声明了静态导入和非静态导入，则这些块必须用空行分隔。它们之间不应有任何其他空行。



在每个块中，导入的类按ASCII字符的排序顺序列出。



3.3.4嵌套类的静态导入



静态导入不用于静态嵌套类。这些类通过常规的导入声明导入。



3.4类声明



3.4.1仅声明了一个顶级类



每个顶级类都位于其自己的源文件中。



3.4.2排序课程内容



放置类的成员和初始化块的顺序可能会对代码的易读性产生很大影响。无论哪种方式，都没有简单而正确的方法。不同的班级可以不同地安排其内容。



重要的是每个类的内容都有逻辑顺序，以便程序员阅读代码可以解释它。



3.4.2.1重载的代码不应拆分



当一个类具有多个同名的构造函数或方法时，必须按顺序放置它们，而不必在其间插入其他代码。



4.格式化



术语



类，方法或构造函数的主体是块构造。



请注意，根据第4.8.3.1节，任何数组初始化器也可以视为块构造。



4.1花括号



4.1.1在任何可能使用的地方都应使用弯括号



如果表达式的主体为空或仅包含一行代码，则在、、、、、和do-while中使用花括号。



4.1.2非空白块：K＆R样式



对于非空块和块结构，根据Kernighan和Ritchie（“埃及括号”）的样式放置花括号（为清楚起见，我们决定添加一些代码来演示这些规则-译者注）：



  • 左括号前没有换行：


// 
if (true) { 

// 
if (true)
{


  • 在左括号后进行换行：


// 
while (true) {
  // code

// 
while (true) { // code


  • 在右括号之前进行换行：


// 
for () {
  // code
}

// 
while (true) { /* code */ }

// 
if (true) {
  /* code */ }


  • 仅当括号结束于方法，构造函数或非匿名类的表达式或主体时，才会在右括号后发生换行。如果在圆括号后接else，catch或分号，则不进行换行


正确执行规则的示例： 



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可以压缩空块



空块或空块构造可以遵循K＆R样式（如第4.1.2节中所述）。这样的块也有可能在打开后立即关闭，而{}内没有字符或换行符。当块是包含if-else或try-catch-finally的多块表达式的一部分时，此规则不适用。



例子： 



// 
void doNothing() {}

//  
void doNothingElse() {
}

// :       
try {
  doSomething();
} catch (Exception e) {}


4.2缩进两个空格



每次打开新的块或块结构时，向右的偏移量都会增加两个空格。当一个块结束时，下一行代码的开头将移至上一个偏移量级别。偏移量级别适用于该块以及该块中的注释（请参见第4.1.2节中的示例）。



4.3每行一个表达式



每个表达式以换行符结尾。



4.4将行宽限制为100个字符



Java代码的行宽限制为100个字符。“字符”是指任何Unicode元素。除下述内容外，每条超过宽度限制的线都必须按照第4.5节中的说明进行包装。



例外情况：



  1. , (, URL Javadoc JSNI- )
  2. package import (. 3.2 3.3)
  3. ,


4.5





当原本可能位于同一行的代码分成多行时，这种现象称为换行。



没有公认的明确公式可以确切确定在每种情况下应如何进行换行。通常，有几种方法可以用同一段代码来换行。



通常进行包装以避免行宽溢出。但是，即使代码保持在允许的宽度内，也可以根据作者的决定将其换行。



分配辅助方法或局部变量可以解决行宽溢出问题，而无需包装代码


4.5.1转让地点



关于换行符的第一条准则是：最好在较高的语法水平上进行换行符。同样：



1.当在非赋值语句上换行时，在字符之前进行换行。



此规则也适用于以下“类似于操作员”的字符：



  • 分割点“。”
  • 引用方法“ ::”的双冒号
  • 括号中的“＆”号<T扩展Foo＆Bar>
  • catch块中的定界符（FooException | BarException e）


2.将字符串包装在赋值语句上时，通常在字符后进行包装，但是可以接受另一种解决方案，



这也适用于for-each循环的冒号。



3.换行时的方法或构造函数的名称仍附加在左括号“（”处



。4.换行时的逗号“，”保留在其前面的元素中



5.决不要将换行直接直接包裹在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节），



也可以在各处使用空白行来提高代码的可读性，例如在表达式之间将代码组织为逻辑小节。不鼓励但不禁止在类的第一个成员或初始化块之前，或在最后一个成员或类的初始化块之后的空字符串。



允许使用多个连续的空白行，但不是必需的或不鼓励使用。



4.6.2空间



除了语言本身或本文档其他规则的要求以及不计算文字和注释（包括Javadoc）以外，ASCII表中的单个空格只能出现在以下位置：



1.分隔任何保留字（例如， for或catch，并在其后加上2的开头括号“（”



。当分隔任何保留字（例如else或catch）时，并在其后跟一个封闭的花括号“}”



。3在任何开头的花括号之前，“ {”，两种情况除外：



  • @SomeAnnotation（{a，b}）
  • 字符串[] [] x = {{“ foo”}}; -{{根据下面的第8条不是必需的


4.在任何二元或三元运算符的任何一侧，



此规则也适用于以下运算符：



  • ＆符内尖括号：<T扩展Foo＆Bar>
  • 包含多个异常的catch块中的分隔符：catch（FooException | BarException e）
  • for-each中的冒号“：”
  • 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不需要水平对齐



术语



水平对齐是在代码中添加不同数量的额外空间以使某些元素显示在上一行中其他元素下方的一种做法。



本指南允许但不要求这种做法。也没有必要在已经应用了代码的那些部分中保持对齐。



带有和不带有对齐的示例： 



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[] {
  0, 1, 2, 3
}
                        
new int[] {
  0, 1,
  2, 3
}

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

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


4.8.3.2没有C样式的数组声明



方括号放在类型之后，而不在变量之后：String [] args，而不是String args []。



4.8.4 switch语句



术语



一组或多组语句位于切换块内。每个组均包含一个或多个标签（均为FOO：和default :），后跟一个或多个语句（对于最后一组，则为一个或多个）。



4.8.4.1偏移



与其他任何块一样，切换块的内容偏移2个空格。



就像在打开块一样，在开关块标签之后进行换行，并且偏移量增加了2个空格。与关闭块时一样，每个后续标签都返回到先前的偏移级别。



4.8.4.2对通过段落进行评论



在一个块中，每组语句要么通过切换提前终止（使用break，continue，return或引发异常），要么用注释标记以指示代码执行将在下一组中继续执行。任何传达``通过''（通常//失败）想法的评论都足够。在开关块的最后一组中，不需要此注释。例： 



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


请注意，注释不是放在案例1之后，而是放在语句组的末尾。



4.8.4.3始终使用默认值



switch语句必须包含默认标签，即使其中没​​有代码。



例外：如果枚举类型的开关块包含显式的情况，该开关块包含该类型的所有可能值，则可能不使用默认值。这使IDE或其他静态分析工具可以发出警告，指出某些情况未包括在内。



4.8.5注释



应用于文档，块或方法的注释紧随doc块之后。每个注释都在其自己的行上列出（即，每行一个注释）。这些换行符不是换行符（请参见第4.5节），因此缩进级别不会增加。例： 



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


例外：不带参数的单个注释可以与第一条签名行一起显示，例如： 



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


应用于字段的注释也立即出现在doc块之后，但是在这种情况下，可以在一行上列出多个注释（可能已参数化），例如： 



@Partial @Mock DataLoader loader;


没有用于格式化参数，局部变量或类型的注释的特殊规则。



4.8.6评论



本节专门介绍实现注释。在第7节中将单独讨论Javadoc。



任何换行符之前都可以带有任意数量的空格，后跟实现注释。此注释使该行变为非空。



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数字文字



长型使用大写L而不是小写（以免与数字1混淆）。例如，使用300_000_000L而不是300_000_000l。



5.命名



5.1所有标识符的一般规则



标识符仅使用ASCII字母和数字，并且在以下某些情况下使用下划线。



因此，每个有效的标识符名称都与正则表达式\ w +（出现一次或多次的字母数字字符）匹配。



使用特殊后缀或前缀的名称，例如name_，mName，s_name或kName，与本教程的样式不符。



5.2不同类型标识符的规则



5.2.1软件包名称



程序包名称必须使用小写字母，没有驼峰或下划线。



正确：com.example.deepspace

不正确：com.example.deepSpace或com.example.deep_space



5.2.2类名



类名以UpperCamelCase样式（大写的首字母）书写。



类名通常是名词或名词短语。例如，Character或ImmutableList。



接口名称也可以是名词或名词短语（例如List），但有时它们也可以是形容词或形容词组合（例如Readable）。



命名注释类型没有特定的规则，甚至没有完善的约定。



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



5.2.3方法名称



方法名称以lowerCamelCase样式编写。



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



下划线可以在JUnit测试方法名称中使用，以分隔名称中的逻辑组件。此外，每个组件均以LowerCamelCase样式编写。典型的模式是： 



<methodUnderTest>_<state>, , pop_emptyStack


没有唯一正确的方法来命名测试方法。



5.2.4常量名称



常量以CONSTANT_CASE样式命名：所有字母均为大写，每个单词之间用下划线分隔。但是常数到底是什么？



常量是静态的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非常数字段名称



非常量（静态或非静态）字段的名称以lowerCamelCase样式编写。



这些字段的名称通常是名词或名词短语。例如，computeValues或index。



5.2.6参数名称



参数名称以lowerCamelCase样式编写。



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



5.2.7局部变量名称



局部变量名称以lowerCamelCase样式编写。



即使局部变量是最终变量且不可变，它们也不被视为常量，并且不应以与常量相同的样式编写。



5.2.8类型变量的名称



每个类型变量均根据以下两种样式之一进行命名：



  • 单个大写字母，后跟一个常规数字（例如，E，T，X，T2）
  • 以类名形式的名称（请参见第5.2.2节），后跟大写字母T（例如：RequestT，FooBarT）。


5.3骆驼风格（camelCase）



有时，有多种方法可以将英语短语转换为骆驼风格，例如缩写或“ IPv6”或“ iOS”之类的非典型表达式。



为了提高可预测性，本指南列出了以下（示例性）方案。



从名称的原始形式开始：



1.将短语转换为常规ASCII并删除所有撇号。例如，可以将“穆勒算法”转换为“穆勒算法”



。2.将结果划分为单词，丢弃空格和任何剩余的标点符号（通常为连字符）：



  • 建议：如果任何单词已经具有通常的“驼峰”样式的通用形式，请将其划分为各个组成部分（例如，“ AdWords”将转换为“ ad words”）。请注意，“ iOS”之类的单词并不是真正的骆驼风格。它不符合任何约定，因此该建议不适用。


3.现在将所有内容都转换为小写（包括缩写），然后将第一个字符转换为大写：



  • ...每个字都能达到UpperCamelCase风格，或者
  • ...除了第一个达到LowerCamelCase样式的单词以外的所有单词


4.最后，将所有单词连接到一个标识符中，



请注意几乎完全忽略了原始单词的大小写。



例子：

原始形式 对 错误
“ XML HTTP请求” XmlHttpRequest XMLHTTPRequest
“新客户ID” newCustomerId newCustomerID
“内部秒表” 内部秒表 innerStopWatch
“在iOS上支持IPv6吗？” supportsIpv6OnIos 支持IPv6OnIOS
“ YouTube导入程序” YouTubeImporter

YoutubeImporter *


*允许但不建议。



注意：某些英语单词使用连字符模棱两可：例如，“ nonempty”和“ non-empty”都是正确的，因此方法名checkNonempty和checkNonEmpty也都是正确的。



6.编程实践



6.1始终使用@Override注释



实际覆盖该方法时，将使用@Override批注标记该方法。这既适用于后代类的方法，其覆盖父类的方法，也适用于接口方法，其覆盖超接口的方法。



例外：如果父方法标有@Deprecated批注，则可以省略批注。



6.2不要忽略捕获的异常



在某些情况下，您不需要采取任何措施来响应捕获的异常是非常罕见的（典型的解决方案是记录该异常，或者，如果认为它是“不可能的”，则将该异常作为AssertionError抛出）。



以下是一个示例，带有解释性注释，当确实适合在catch块中不执行任何操作时： 



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对于静态成员，请使用类名



必须通过类名称来引用静态类的成员，而不是通过引用类对象或通过返回该对象的表达式来引用： 



Foo aFoo = ...;
Foo.aStaticMethod(); // 
aFoo.aStaticMethod(); // 
somethingThatYieldsAFoo().aStaticMethod(); //


6.4不要使用终结器



您很少需要重写Object.finalize方法。



提示：



不要这样做。如果您确实需要它，请先阅读并真正全面地了解有效的Java项目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，并且这四种类型永远不会带有空描述。如果一个块标记不适合一行，则将续行从@缩进四个（或更多）空格。



7.2最终摘要



每个Javadoc块均以简短的摘要片段开头。此代码段非常重要：它是出现在特定上下文中的唯一文本，例如类和方法索引。



此代码段是名词或动词短语，而不是完整的句子。它不是以A {@code Foo}是...或此方法返回...开头，也不会形成一个完整的肯定句，例如Save the record。但是，此段落大写并标点符号，好像是完整的句子一样。



提示：编写简单的Javadoc（例如/ ** @返回客户ID * /）是一个常见错误。这是不正确的，应更正为/ **返回客户ID。* /。



7.3应用Javadoc时



Javadoc至少存在于每个公共类以及此类的每个公共和受保护成员中，但在某些情况下（如下所述）除外。

可能会出现其他Javadoc，如第7.3.4节“可选Javadoc”中所述。



7.3.1异常：描述自己的方法



Javadoc对于诸如getFoo之类的简单明了的方法是可选的，以防万一，您实际上只能说“ Returns foo”。



重要说明：引用此例外情况以忽略普通读者可能需要的相关信息是不合适的。



例如，对于名为getCanonicalName的方法，请不要省略文档（理由是该方法名称仅显示/ **返回规范名称。* /）如果阅读代码的普通人甚至都不怀疑“规范名称”是什么意思！



7.3.2例外：覆盖

Javadoc并不总是伴随有从超类（或超级接口）中覆盖方法的方法。



7.3.4可选的Javadoc



根据需要或期望，其他类和成员都附带Javadoc。



每当使用实现注释来定义类或成员的通用目的或行为时，该注释就会被编写为Javadoc（使用/ **）。



可选的Javadoc不必遵循第7.1.2、7.1.3和7.2节的格式设置规则，尽管当然建议这样做。



该翻译也可以在我们的博客上找到。


More articles:


All Articles