编写注释属于编码流程的一部分,此过程十分非常重要,清晰的注释能让你的代码被阅读显得易于理解,提高队友之间的合作效率,在写代码的时候一定要注意注释的规范。
精简,用最简短的语言全面清晰描述
遵循编程语言的规范,如 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接口,进行挂号
* 若挂号成功,更新挂号信息,并且如果系统存在该挂号医生的信息,则患者会自动关注该医生
*/