team-standard/注释规范.md

注释规范

规范目的

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

基本原则

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

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

• 使用专业术语表达

注释规范优点

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

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

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

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

• 可让注释生成接口文档

注释规范

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

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

单行注释

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

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

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

示例：

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

多行注释格式

最少三行

前边留空一行

示例：

private String foo;

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

}

多人合作注释

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

示例：

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());
}

注释模块注释约定

文件头注释

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

• 规范约定示例

/**
 * 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}
  */
  

函数注释

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

• 规范约定示例

/**
 * 根据医院 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 支持自动补全，输入 /** 回车即可。

核心业务逻辑注释

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

单行注释

用于变量或者流程概述

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

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

多行注释

一般用于核心步骤的诠释

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

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