注释规范.md 4.0 KB

注释规范

规范目的

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

基本原则

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

  • 遵循编程语言的规范,如 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接口,进行挂号
* 若挂号成功,更新挂号信息,并且如果系统存在该挂号医生的信息,则患者会自动关注该医生
*/