# 注释规约

> 来源: Java开发手册（嵩山版）— 一(九) 注释规约

## 【强制】规则

### 1. 类/属性/方法用 Javadoc

类、类属性、类方法的注释必须使用 Javadoc 规范，使用 `/**内容*/` 格式，不得使用 `// xxx` 方式。

### 2. 抽象方法必须 Javadoc

包括返回值、参数、异常说明，还必须指出该方法做什么事情、实现什么功能。

### 3. 类必须添加创建者和日期

> **正例**:
> ```java
> /**
>  * @author yangguanbao
>  * @date 2016/10/31
>  */
> ```

### 4. 方法内注释

- 单行注释: 在被注释语句上方另起一行，使用 `//`
- 多行注释: 使用 `/* */`，注意与代码对齐

### 5. 枚举字段必须有注释

说明每个数据项的用途。

## 【推荐】规则

### 6. 中文注释优先

专有名词与关键字保持英文原文即可。

> **反例**: "TCP 连接超时" 解释成 "传输控制协议连接超时"

### 7. 代码修改时同步修改注释

尤其是参数、返回值、异常、核心逻辑等。

### 8. 删除未使用的字段/方法/参数/变量

### 9. 谨慎注释代码

在上方详细说明，而不是简单地注释掉。如果无用则删除。

### 10. 注释要求

- 准确反映设计思想和代码逻辑
- 描述业务含义

### 11. 注释精简

好的命名和代码结构是自解释的，注释力求精简准确。

### 12. 特殊注释标记

请注明标记人与标记时间，及时清理:

| 标记 | 用途 |
|------|------|
| `TODO` | 待办，需实现但尚未实现的功能 |
| `FIXME` | 错误，不能工作，需要及时纠正 |