# 注释规范

## 规范目的
编写注释属于编码流程的一部分，此过程十分非常重要，清晰的注释能让你的代码被阅读显得易于理解，提高队友之间的合作效率，在写代码的时候一定要注意注释的规范。

##  基本原则

- 精简，用最简短的语言全面清晰描述

- 遵循编程语言的规范，如 javadoc 规范

- 使用专业术语表达


## 注释规范优点

- 关键核心逻辑注释、易于对业务流程实现的理解，即提高代码的可读性

- 代码注释减少团队之间无必要的沟通，提高开发效率

- 提高项目代码的可维护性

- 遵循编程语言规范，让 `IDE` 更加懂你，即代码智能提示

- 可让注释生成接口文档



## 注释规范

### 注释必须用准确的语言来描述

**中英文不限**，如果你的英文水平一般，就用准确的中文描述。

### 单行注释

注释符后，必须跟注释内容保留一个空格

可独占一行, 缩进与下一行代码保持一致

可位于一个代码行的末尾，注释符前要有一个空格

示例：

```javascript
// Good
if (condition) {
    // if you made it here, then all security checks passed
    allowed();
}
var zhangsan = "zhangsan"; // 双斜线前后都保留一个空格
```

### 多行注释格式

最少三行

前边留空一行

示例：

```java
private String foo;

/**
 * 获取公众号用户信息
 *
 * @param userId 用户 id
 */
public void getOfficialUserInfo(int userId) {

}
```

### 多人合作注释

同一个文件的代码可能被多个人修改，这个时候可以标识出谁改动了哪些部分。

示例：

```java
public void notifyArtDoctor(int userId) {
   final String tplCode = "TPL_1013";
   // 产品提出修改: 点击模板消息，进入药事快讯页面不进入具体文章。
   // edited on 2018-08-17 14:15:06 by Walker
   String url = String.format("%s/doctorwe/drugNews", bizConfigurer.getYwtHttpsMsiteDomain());
}
```


## 注释模块注释约定

### 文件头注释

简单描述该文件的作用、作者以及创建时间

- 规范约定示例

```java
/**
 * Guava cache 工具类，主要用于提供单例 Cache 对象，便于缓存管理
 * 由于 Guava cache 不支持在 runtime 修改 maxSize, expireTime 这些属性，只能初始化的时候指定。
 * @author Walker
 * Created on 2020/6/19
 */
public final class CacheUtil {

}
```

- `IDE` 配置

```
/**
 * 
 * @author ${USER}
 * Created on ${DATE}
 */
```

### 函数注释

包含函数名称、函数功能作用描述、参数、异常、返回值、作者信息

- 规范约定示例

```java
/**
 * 根据医院 id 获取核酸检测费用配置
 *
 * @param hospitalId 医院 id
 * @return 费用，单位：分
 * @throws AppMessageException 找不到配置时抛出异常
 * @author Walker
 */
public int getNatFeeConfig(int hospitalId) throws AppMessageException {
    NatFeeConfig config = natFeeConfigRepository.findFirstByHospitalIdAndDeletedFalse(hospitalId);
    if (config == null) {
        throw new AppMessageException(String.format("根据医院 id(%d) 找不到配置，请联系系统管理员", hospitalId));
    }
    return Checker.getIntegerValue(config.getAmount());
}
```

- `IDE` 配置

IDEA 支持自动补全，输入 `/**` 回车即可。

### 核心业务逻辑注释

对于**业务逻辑复杂 或 特定业务规则 的代码片段务必编写注释**

#### 单行注释

用于变量或者流程概述

  > 注释符号后需要有一个空格

```java
// 0 元订单，直接支付成功
savedNatOrder.setStatus((savedNatOrder.getStatus() | NatOrderStatusEnum.PAID.getValue()));
savedNatOrder.setPayTime(new Date());
savedNatOrder.setPaymentStatus(PaymentStatusEnum.Success.getValue());
```

#### 多行注释

一般用于核心步骤的诠释

  > 诠释流程 或详细描述 或注释单元项归类总称

```java
/**
* 调用HIS接口，进行挂号
* 若挂号成功，更新挂号信息，并且如果系统存在该挂号医生的信息，则患者会自动关注该医生
*/
```