java编码规范

Posted 2020-09-08

 

1. 介绍 1.1. 术语 1.2. 文档说明 2. 源文件规范 2.1. 文件名 2.2. 文件编码 2.3. 特殊字符 2.3.1. 空格 2.3.2. 特殊转义字符 2.3.3. 非ASCII字符 3. 源文件组织结构 3.1. 许可证（License）或版权声明（Copyright） 3.2. package语句 3.3. import语句 3.3.1. 禁止通配符import 3.3.2. 不换行 3.3.3. 顺序 3.3.4. 删除未使用的import语句 3.4. 类声明 3.4.1. 唯一的顶层类 3.4.2. 类成员顺序：有一定的逻辑顺序即可 3.4.3. 重载（Overload）方法必须放在一起

4. 代码格式 4.1. 花括号 4.1.1. 不得省略花括号 4.1.2. 非空块中花括号的使用 4.1.3. 空代码块中花括号的使用 4.2. 块缩进：4个空格 4.3. 每行只写一条语句 4.4. 列宽：120字符 4.5. 换行 4.5.1. 何处换行 4.5.2. 至少用8个以上的空格缩进连续的行 4.6. 空白 4.6.1. 空行 4.6.2. 空格 4.7. 表达式圆括号 4.8. 其他说明 4.8.1. 枚举类 4.8.2. 变量声明 4.8.3. 数组 4.8.4. switch语句 4.8.5. 注解（Annotation） 4.8.6. 注释 4.8.7. 修饰符 4.8.8. 数字

5. 命名 5.1. 通用命名规范 5.2. 特定类型命名规范 5.2.1. 包命名 5.2.2. 类命名 5.2.3. 方法命名 5.2.4. 常量命名 5.2.5. 变量命名 5.2.6. 参数命名 5.2.7. 局部变量命名 5.2.8. 泛型类型变量命名 5.3. 驼峰命名方式定义 6. 编程实践 6.1. 使用@Override 6.2. 异常捕获：不推荐Ignore 6.3. 静态成员： 6.4. Finalizer：禁用 7. Javadoc 7.1. 格式 7.1.1. 通用 7.1.2. 段落 7.1.3. @条目相关 7.2. 摘要 7.3. Javadoc应该应用在哪些场合 7.3.1. 例外情况：方法本身已经足够说明用途 7.3.2. 例外情况：覆盖（Override）方法 8. 工具支持

本文出自http://www.cnblogs.com/dubo-/

1. 介绍

为统一公司Java项目编码规范，提高可读性，特制定本规范。

本规范同样适用于android项目。

本规范基于，主要的区别如下：

• 保留了原有规范的4空格缩进和120字符列宽限制

• 放松了对import语句的组织方式要求。只要有一定逻辑性即可，不做严格限制。但要求未使用的import语句必须删除

• 对Android的成员变量命名允许了例外。

  • 非public非static的变量可以使用m开头
  • 非常量的static变量可以使用s开头

• switch语句禁止了case贯穿，同时要求default必须被终止。

• 允许特殊场景下的单字符参数命名，例如使用x、y表示坐标。

• 禁用了枚举类的单行风格

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

• 禁用了无参数注解的不换行风格

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

  @Partial @Mock DataLoader loader;
  

• 增加了对使用拼音命名的说明：不建议但允许少量例外。

• 禁止使用连续的空行进行分隔。

• 禁用了一种数组初始化换行的风格。

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

• 禁止使用连续的空格分隔。不再允许使用增加空格来进行对齐的风格。

• 允许包名中包含数字，例如 org.apache.logging.log4j

• JavaDoc允许多种形式的段落分隔方式

相对于原先的百度Java编码规范，本规范做出了大量更加严格的限制，但是7、8、9三节的有关编程实践的规定基本取消。部门可根据自己需要对规范进行加强。

1.1. 术语

除非特别约定，我们使用以下术语：

• 类用于指代所有类（class）、枚举（enum class）、接口（interface）以及注解（annotation）。
• 注释仅用于指代行间注释，Javadoc用于指代文档注释。

1.2. 文档说明

本文中所使用的示例代码不具备唯一权威性。示例代码只代表一种符合规范的写法，也可能存在其他符合规范的不同写法。

2. 源文件规范

2.1. 文件名

[J001] 源文件名必须和它包含的顶层类名保持一致，包括大小写，并以.java作为后缀名。

2.2. 文件编码

[J002] 所有源文件编码必须是UTF-8

2.3. 特殊字符

2.3.1. 空格

[J003] 除了换行符之外，ASCII空格（0x20）是唯一合法的空格字符。这意味着

• 所有在源代码中（包括字符、字符串以及注释中）出现的其他空格字符需要转义,例如Tab用\\t表示。
• 缩进必须使用空格而不是Tab

2.3.2. 特殊转义字符

[J004] 对于有特殊转义表示的字符（\\b, \\t, \\n, \\f, \\r, \\", \\\', \\\\），禁止使用其它等价转义方式。例如\\012或者\\u00a表示。

2.3.3. 非ASCII字符

对于非ASCII字符，可以使用实际字符（如∞）或者它的Unicode转义（如\\u221e），取决于哪种写法的可读性更好。

使用注释有助于增强可读性

示例：

Example	Discussion
String unitAbbrev = "μs";	最佳写法，无需注释就可以理解
String unitAbbrev = "\\u03bcs"; // "μs"	虽然合法但是很没有必要的写法
String unitAbbrev = "\\u03bcs"; // Greek letter mu, "s"	虽然合法但是很难理解的写法
String unitAbbrev = "\\u03bcs";	让人完全读不懂的写法
return \'\\ufeff\' + content; // byte order mark	很好的写法，用Unicode转义来表示非打印字符，并且有合适的注释帮助阅读者理解

3. 源文件组织结构

[J005] 源文件必须按顺序由以下部分组成：

1. 许可证（License）或版权声明（Copyright）
2. package语句
3. import语句
4. 唯一的顶层类

每两部分之间用一个空行分隔

3.1. 许可证（License）或版权声明（Copyright）

如果文件有许可证（License）或版权声明（Copyright），放在最开头。如果没有的话，此部分可以忽略。

3.2. package语句

[J007] package语句占据单独一行不换行，允许超出120字符列宽限制。

3.3. import语句

3.3.1. 禁止通配符import

[J008] 无论是static还是非staic imports，均禁止使用通配符import。

3.3.2. 不换行

[J009] 每条import语句占据单独一行不换行，允许超出120字符列宽限制。

3.3.3. 顺序

[J010] import语句需按照一定的逻辑顺序组织。

可参考以下的组织形式，不强制：

按以下顺序进行分组，每两组之间用一个空行分隔。

1. 所有的static import语句

2. com.dubo import语句（仅当源文件属于com.dubo时适用）

3. 第三方包。每个顶层包独立一组，按ASCII顺序排列

   例如：android, com, junit, org, sun

4. java import语句

5. javax import语句

组内不包含空行，按照所import的包名的ASCII码顺序排列。

3.3.4.删除未使用的import语

[J013] 所有未使用的import语句应该被删除。

3.4. 类声明

3.4.1. 唯一的顶层类

[J011] 每个源文件只允许包含唯一一个顶层类。

以下写法虽然符合Java语法，但禁止使用

public class A {
}

class B {
}

必须把B放在一个独立的源文件中

3.4.2. 类成员顺序：有一定的逻辑顺序即可

不规定严格的类成员顺序，但需要遵循一定逻辑规律，让阅读者容易理解。例如不建议把新添加的方法一律放在最后，而是应该插入到合适的地方。

3.4.3. 重载（Overload）方法必须放在一起

[J012] 重载的方法必须放在一起，即同名的构造函数或方法之间禁止插入其他成员。

4. 代码格式

4.1. 花括号

4.1.1. 不得省略花括号

[J014] 在if、else、for、do和while语句中，即使没有语句或者只有一行，也不得省略花括号。

4.1.2. 非空块中花括号的使用

[J015] 在非空代码块中使用花括号时要遵循K&R风格（Kernighan and Ritchie Style）：

• 左花括号（{）前不能换行，在其后换行。
• 在右花括号（}）前要有换行。
• 如果右花括号是一句语句、一个方法、构造函数或非匿名类的结尾，其后需要换行。

return new MyClass() { // 左花括号前不能换行，在其后换行
    @Override
    public void method() {
        if (condition()) {
            try {
                do {
                    something();
                } while (!stop()); // do-while中间的右花括号后
            } catch (ProblemException e) { // try-catch中间的右花括号后无需换行
                recover();
            } // try-catch结束，右花括号后需要换行
        } else { // if-else中间的右花括号后无需换行
            doSomethingElese();
        } // if-else结束，右花括号后需要换行
    }
}; // 匿名类结尾的右花括号后无需换行

4.1.3. 空代码块中花括号的使用

[J016] 如果一个代码块是空的，可以直接使用{}。除了if/else-if/else和try/catch/finally这样的多块语句：

EmptyConstructor() {}

4.2. 块缩进：4个空格

[J017] 每次开始书写一个新的代码块时，使用4个空格进行缩进，在代码块结束时，恢复之前的缩进级别。

4.3. 每行只写一条语句

[J018] 每条语句之后都要换行。

4.4. 列宽：120字符

[J019] 列宽必须为120字符，以下情况可以不遵守列宽限制：

• 无法限制宽度的内容，比如注释里的长URL
• package和import语句
• 注释中需要被粘贴到Shell里去执行的命令

4.5. 换行

换行指的是一行语句由于某些限制（例如列宽）需要分为多行的情况。

4.5.1. 何处换行

[J006] 换行原则：尽量在高层次的语法元素处换行。此外：

• 在非赋值操作符前换行，该原则也适用于这些符号：点（.），泛型类型绑定中的与符号（<T extends Foo & Bar>），catch中的竖线（catch (FooException | BarException e)）
• 在赋值操作符（=）后换行，该原则也适用于foreach语句中的:。例外：在给注解（Annotation）中的数组类型参数赋值时，应参考数组初始化形式，优先选择在左花括号（{）后面换行，详见下面的例子。
• 方法、构造函数名字和左圆括号（(）之间不换行
• 逗号（,）紧跟前面的内容不换行

4.5.2. 至少用8个以上的空格缩进连续的行

在连续换行时，第二行要比上一行多缩进8个空格。从第三行开始，可以视情况在上一行缩进基础上增加更多空格。一个原则是如果同一条语句的两行采用同样的缩进，那么它们打头的语法元素必须在语法树上处于同一级。详见下面最后一个例子。

public class Example {
    @ExampleAnnotation(stringArrayValue = {
        "value1", "value2", "value3", "value4", "value5", "value6", "value7", "value8"
    })
    public void exampleMethod() {
        // 在非赋值操作符前换行
        method1("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
                + "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz");

        // 该原则也适用于这些符号：点（.）
        method2("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
                .method1("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz");

        // 在赋值操作符（=）后换行
        String varWithVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongName =
                "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";

        // 该原则也适用于foreach语句中的:
        for (int anotherVarWithVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongName :
                new int[] {0, 1, 2, 4, 5, 6, 7, 8, 9}) {
        }

        // 方法、构造函数名字和(之间不换行
        methodWithVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongName(
                "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz");

        // 逗号,紧跟前面的内容不换行
        methodWithTwoParameter("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
                "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz");

        // 至少用8个以上的空格缩进连续的行
        methodWithMultipleParameter("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
                "如果同一条语句的两行采用同样的缩进，那么它们打头的语法元素必须在语法树上处于同一级"
                    + "如果有多行需要换行可以按照需要调整为更多空格", // 不一定需要再次缩进8格，只要比上一级多就行
                "如果同一条语句的两行采用同样的缩进，那么它们打头的语法元素必须在语法树上处于同一级");

    }
}

4.6. 空白

4.6.1. 空行

[J020] 在以下情况下增加空行：

• 在类的不同的成员间增加空行，包括：成员变量、构造函数、方法、内部类、静态初始化块、实例初始化块等

  • 两个成员变量声明之间可以不加空行。空行通常用于对成员变量进行逻辑分组。

• 方法体内，按需增加空行，以便从逻辑上对语句进行分组

禁止使用连续的空行。

4.6.2. 空格

[J041] 除了语法要求，字符串内的空格，以及JavaDoc里的空格，需要在下列情况里使用空格

• 保留字（比如if、for和catch）和随后的左圆括号（(）之间要有一个空格

• 保留字（比如else和catch）和之前的右花括号（}）之间要有一个空格

• 在任意左花括号（{）之前要有一个空格。@SomeAnnotation({a, b})和String[][] x = {{"foo"}};这两种情况除外。

• 在二目和三目运算符两边各要有一个空格。该规则同样适用于<T extends Foo & Bar>中的&，catch (FooException | BarException e)中的|，以及foreach中的:

• 在逗号（,）”、冒号（:）和类型转换用的右圆括号（)）后要有一个空格

• 在用于行末注释的//前后各要有一个空格

• 在声明语句的类型和名称之间要有一个空格，比如List<String> list

• 以下两种初始化数组的形式均可接受：

  • new int[] {5, 6}
  • new int[] { 5, 6 }

• 除行首缩进、注释和字符串内的空格以外，禁止使用连续的空格

public class Example {
    public List<Element> getAllValidElements(String[] nodes) throws PermissionDeniedException {
        List<Element> result;
        for (int i = 0; i < nodes.length; ++i) {
            if (checkPermission(nodes[i])) {
                for (int id : getAllElementIdList(nodes[i])) {
                    Element e = (Element) getElement(id);
                    if (isValidElement(e)) {
                        result.add(e);
                    }
                }
            } else {
                throw new PermissionDeniedException("Can not access node " + nodes[i]);
            }
        }
        return result;
    }
}

4.7. 表达式圆括号

由于不能保证所有人都清楚Java操作符优先级，因此推荐在表达式中增加圆括号用来明确其中运算的优先级。不做强制要求。

4.8. 其他说明

4.8.1. 枚举类

用逗号(,)分隔每个枚举常量，也可以用换行。

enum Color {
    RED,
    GREEN,
    YELLOW
}

enum Action {
    CREATE, READ, UPDATE, DELETE
}

4.8.2. 变量声明

• [J021] 一行只声明一个变量
• 在需要时声明变量，声明后尽快初始化

4.8.3. 数组

• 初始化换行原则

  数组初始化通常不换行。在需要换行时，原则和普通代码块保持一致

例如以下示例均合法

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

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

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

• 不要使用C的数组声明风格

  [J022] 必须用String[] args的方式来声明数组，而非String args[]。

4.8.4. switch语句

[J024] 说明：一个switch块包含了一个或多个语句组。每组都以一个或多个标签开头（如case 0:或者default:），后面跟着一个或多个语句。

• 缩进

  • switch块内的内容，使用4个空格缩进。
  • 在每个标签后换行，换行后缩进4个空格，下一个标签恢复原缩进。

• [J023] case贯穿：禁止

  • case必须被终止（break、return和抛出异常）。不允许使用case贯穿，这种风格容易导致bug。如有实际需要的场景，应使用if-else来实现。

• default

  • 每个switch中都要有default。
  • default也必须被终止（break、return和抛出异常）。
  • 在default预期不可能被执行的时候，应执行抛出异常等可以有效发现bug的动作。

switch (dayOfWeek) {
    case MONDAY:
        ...
        break;
    case TUESDAY:
        ...
        break;

    ...

    default:
        throw new RuntimeException("Unhandled case " + dayOfWeek);
}

4.8.5. 注解（Annotation）

[J025] 添加在类、方法、构造函数、成员属性上的注解（Annotation）直接写在注释块之后，每个注解独占一行。

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

4.8.6. 注释

[J026] 块注释的缩进与其上下文保持一致，可以使用/* ... */或者// ...的风格。多行的块注释中*必须对齐。

/*
 * 可以
 * 这样
 */

// 也可以
// 这样

/* 或者甚至
 * 这样 */

4.8.7. 修饰符

[J027] 当同时使用多个修饰符时，按照下列顺序：

public protected private abstract static final transient volatile synchronized native strictfp

4.8.8. 数字

[J028] 长整型数字必须使用大写字母L结尾，不能使用小写字母l，以便和数字1进行区分。例如使用3000000000L而不是3000000000l

5. 命名

5.1. 通用命名规范

所有的标识符只允许使用ASCII字符和数字。合法的标识符命名必须能够匹配正则表达式：\\w。

禁止使用一些特定的前缀和后缀，比如：name_、mName、m_name。Android的成员变量命名允许例外，详见2.5.2.5 变量命名。

不建议使用中文拼音来命名。例外：

• 得到广泛认可的中文产品名，像贴吧、凤巢等
• 以个人命名的算法或数据结构的实现

5.2. 特定类型命名规范

5.2.1. 包命名

[J029] 包名只允许使用小写字母和数字，并且单词直接连接（不允许使用下划线）。比如：com.baidu.somebusiness，而com.baidu.someBusiness或com.baidu.some_business是不允许的。

5.2.2. 类命名

[J030] 类名必须遵循大写字母开头的驼峰式命名方式（UpperCamelCase）。

类名通常使用名词或名词短语，比如：Customer、ImmutableList。接口名也可以是名词或名词短语（比如：List），但很多时候会使用形容词代替（比如：Runnable）。

对于注解（Annotation）命名没有特定的规定。

单测类的命名规则必须以被测试类名开始，Test单词结束。比如：BubbleSortTest。

5.2.3. 方法命名

[J031] 方法必须遵循小写字母开头的驼峰式命名方式（lowerCamelCase）。

方法名通常使用动词或动词短语，比如：sendMessage、stop。

在单测方法中可以含有下划线，通常用来指定特定场景：test<测试方法名>_<场景>，比如：testPop_emptyStack。

对于测试方法的命名没有强制性要求，也可以采用其他的命名方式。

5.2.4. 常量命名

[J032] 常量必须为大写单词，下划线分隔的命名方式。但什么是常量则没有特别精确的定义，需要主观判断。

首先常量一定是static final的字段，但是不是所有的static final字段都是常量。一个字段是否是常量需要按照语义进行判断。举例：如果一个变量的状态是可以改变的，那么几乎可以肯定它不是一个常量。仅仅看对象不可改变是不够的。

// 常量
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(\',\');
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 Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};常量通常使用名词或名词短语。

5.2.5. 变量命名

[J033] 非常量的变量（类变量和实例成员变量）名必须采用小写单词驼峰命名方式（lowerCamelCase）。

变量命名通常使用名词和名词短语。举例：computedValue、index。

对于Android，允许一些命名例外：

• 非public非static的变量可以使用m开头
• 非常量的static变量可以使用s开头

5.2.6. 参数命名

[J034] 参数名必须采用小写单词驼峰命名方式（lowerCamelCase）。

严格限制使用单字符命名参数。某些约定俗成不会发生理解偏差的场景可以允许使用单字符参数，例如使用x，y表示坐标的时候。

5.2.7. 局部变量命名

[J035] 局部变量名通常采用小写单词驼峰命名方式（lowerCamelCase），可以自由缩写。

除循环变量和临时变量外，不允许使用单字符命名。

局部变量禁止使用常量命名方式，不管是否标识为final。

5.2.8. 泛型类型变量命名

[J036] 泛型类型变量名必须遵循以下两种方式之一：

• 单独一个大写字母，有时后面再跟一个数字。（例如，E、T2）。
• 类命名的最后接一个大写字母。（例如，RequestT）。

5.3. 驼峰命名方式定义

通常有多种方式将短语组织成驼峰方式，像一些缩写词：IPv6、ios等。为了统一，必须遵循以下几点规则。

1. 将字符全部转换为ASCII字符，并且去掉’等符号。例如，Müller\'s algorithm被转换为Muellers algorithm

2. 在空格和标点符号处对上一步的结果进行切分，组成一个词组。

   • 推荐：一些已经是驼峰命名的词语，也应该在这个时候被拆分。（例如 AdWords 被拆分为 ad words）。但是例如iOS之类的词语，它其实不是一个驼峰形式的词语，而是人们惯例使用的一个词语，因此不用做拆分。

3. 经过上面两步后，先将所有的字母转换为小写，再把每个词语的第一个字母转换为大写。

4. 最后，将所有词语连在一起，形成一个标识符。

注意：词语原来的大小写规则，应该被完全忽略。以下是一些例子：

原始短语                正确写法                              非法写法
"XML HTTP request"      XmlHttpRequest                        XMLHTTPRequest
"new customer ID"       newCustomerId                         newCustomerID
"inner stopwatch"       innerStopwatch                        innerStopWatch
"supports IPv6 on iOS?" supportsIpv6OnIos                     supportsIPv6OnIOS
"YouTube importer"      YouTubeImporter or YoutubeImporter[1]

[1]号表示可以接受，但是不建议使用。

注意：有些词语在英文中，可以用[-]连接使用，也可以不使用[-]直接使用。例如“nonempty”和“non-empty”都可以。因此方法名字为checkNonempty或者checkNonEmpty都是合法的写法。

6. 编程实践

6.1. 使用@Override

在允许的场景下推荐使用@Override来标注方法。包括方法覆盖（Override）了父类的方法、方法实现了接口方法、还有接口方法覆盖（Override）了父接口的方法定义。

存在某些不允许的场景，例如Java SE 5不允许用@Override标注方法对接口的实现。

例外情况：覆盖（Override）的目标方法标识为@Deprecated的情况除外。

6.2. 异常捕获：不推荐Ignore

[J040] 实际编码中仅仅在小部分场景下可以忽略异常不做任何处理。（通常是打印日志，或者重新包装抛出一个新异常）

如果真的不需要处理异常，那么需要在注释中解释。

举例：

try {
    int i = Integer.parseInt(response);
    return handleNumericResponse(i);
} catch (NumberFormatException ok) {
    // it\'s not numeric; that\'s fine, just continue
}
return handleTextResponse(response);

例外情况：在测试Case中，如果这个Case是验证预想中的异常分支，那么可以省略注释解释。

try {
    emptyStack.pop();
    fail();
} catch (NoSuchElementException expected) {
}

补充说明：针对上面这个场景，更推荐下面这种写法

@Test(expected = NoSuchElementException.class)
public void testPopEmptyStack() throws Exception {
    emptyStack.pop();
}

6.3. 静态成员：

当访问一个静态成员的时候，正确的用法是使用类名引用，而不是使用对象或者对象表达式来引用。

Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad

6.4. Finalizer：禁用

[J037] 禁止覆盖（Override）Object.finalize方法。

7. Javadoc

7.1. 格式

7.1.1. 通用

基础的Javadoc格式如下例：

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

7.1.2. 段落

除了第一段之外，后续段落描述应以<p>标签开始。段落首个文字可以紧接着<p>标签，也可以换行重新开始。

/**
 * Represents ....
 *
 * <p>More details here
 */
public class XXX {
    ...
}

/**
 * Represents ....
 *
 * <p>
 * New line is allowed.
 */
public class XXX {
    ...
}

7.1.3. @条目相关

[J038] 在使用标准的@条目时按照@param，@return，@throws，@deprecated的顺序进行排列。这四个条目在使用时描述不能为空。其余条目顺序可以随意。 每个@条目必须占据独立的行。当一行不够需要换行时，使用8个以上的空格缩进。

7.2. 摘要

[J039] 每个类和成员的Javadoc需要以摘要片段来开头。这非常重要，因为Javadoc会自动抽取第一句话显示在索引和方法概述表中。写摘要片段的原则是简洁清晰。它不是一句完整的话，例如This is a ...，而是更接近短语，如A mutable sequence of characters.或Thrown when an exceptional arithmetic condition has occurred.。但在书写时采用类似句子的写法，以大写字母开头，并用.结尾。

7.3. Javadoc应该应用在哪些场合

至少Javadoc应该应用于所有的public类、public和protected的成员变量和方法，除了后面条款列举的例外情况。

除此之外的类和成员有时候也需要Javadoc。例如在需要总体解释一个类、方法、成员的具体实现逻辑的时候，通常会使用Javadoc替代注释。

7.3.1. 例外情况：方法本身已经足够说明用途

对于那些非常显而易见的方法可以不写Javadoc，比如getFoo，写一个Returns the foo的意义不大。

注意：有时候不应该应用此例外来省略一些用户需要知道的信息。例如：getCannicalName。当大部分代码阅读者不知道canonical name是什么意思时，不应该省略Javadoc（或者只写Returns the canonical name也是不行的，需要详细阐述什么是canonical name）。

7.3.2. 例外情况：覆盖（Override）方法

大多数情况下覆盖（Override）方法不需要Javadoc。

5. 工具支持

对所有标记的有“eagle支持”的规则，大家可以本地调用客户端检查代码是否符合这部分规则，另外在发起代码评审（cooder）时也将自动触发检查，结果会以行间评论的形式插入到代码评审中，帮助作者检查代码、帮助评审人评审代码，详细内容点击查看