日常开发中，如何规范使用注释
日常开发中，如何规范使用注释
前言
任何一门语言，都有自己的注释标准，注释的作用就是解释说明程序的文字。
Java中的注释类型有三种：
- 单行注释 //
- 多行注释 /**/
- 文档注释 /** */
一、在项目中如何规范使用注释？
单行注释
- 当代码意义不够明显，在当前代码片段上一行添加注释来解释代码作用
- 一般用在方法内部
// Add boot specific singleton beans
ConfigurableListableBeanFactory beanFactory = context.getBeanFactory();
多行注释
- 基本是用不到，不常用，如果出现大篇幅的注释，那么你这段代码可能需要重新梳理一下逻辑了，重构了。
文档注释
- 一般在类、方法的上一行添加注释，来解释其功能、参数和返回值等
/**
* Run the Spring application, creating and refreshing a new
* {@link ApplicationContext}.
* @param args the application arguments (usually passed from a Java main method)
* @return a running {@link ApplicationContext}
*/
public ConfigurableApplicationContext run(String... args) {
...
}
使用规范
- 不要保留已经不再适用的旧代码注释
- 不要每行都写注释，一些方法名、变量名需要见名知意，包含一定的语义，只有复杂逻辑才需要。
- 修改代码逻辑时，要同步修改注释，不要造成欺骗😭
二、一些常用注释技巧
以下都是基于 IDEA 的使用技巧，如果是其它编辑器可以自己找找有没有类似功能。如果大家有其它小技巧欢迎大家评论区分享一下。
1. TODO 注释的使用
当我们在写业务逻辑的时候，有些方法实现起来可能会比较复杂，或者有些其实是附加逻辑，比如下单完成，发送个消息，但是发送消息依赖与其他同事写的方法，但是其他同事还没写完，这时，避免自己后续忘记就可以用上这个注释技巧, 如下：
public void order(Integer id){
...
// TODO 发送消息通知
...
}
然后在 TODO 栏下面就可以查看我们有多少未完成的 TODO，并且可以快速定位到。
可以在 【View】→ 【Tool WIndows】→ 【TODO】，调出快捷栏。
提交代码的时候设置上【Check TODO】，会提醒我们是否有遗漏的待办事项未处理。
类似的注解 FIXME，这两个是 IDEA 默认会高亮的。如果需要你也可以自定义添加。【File】> 【Settings】> 【Editor】> 【Inspections】>【Todo】, 点击 Add（+）按钮添加一个新关键字，确认好图标，字体颜色，即可。
TODO: 表示此处有待完成的工作或待实现的功能。
FIXME: 指出代码中的错误或不足之处，需要修复。
2. 文档注释模板配置
我们在给类或者方法上添加文档注释的时候，一般会有一些固定格式，便于我们理解。
类上:
/**
* <p>
* Admin启动类
* </p>
*
* @author 曹申阳
* @since 2024-07-29 15:33:35
*/
@SpringBootApplication
@MapperScan("com.itshare.admin.mapper")
public class AdminApplication {
...
}
p 标签记录类的描述，当然你也可以用@description
@author记录作者信息
@since记录创建时间
方法上：
/**
* 根据id查询机构
* @param deptId 部门ID
* @return DeptVO 部门VO
*/
DeptVO getDeptById(Long deptId);
@param描述参数信息
@return描述返回信息
合理使用这些文档注释，可以是我们的项目代码更加清晰，便于团队合作。
当然我们不可能每次都手敲这些注释，好在现在基本都支持自定义模板的功能，使用快捷键就可以为我们自动生成。我们只需要填写好对于的解释即可。
打开 【File】> 【Settings】> 【Editor】> 【File and Code Templates】，找到Class编辑后点击 【apply】即可。
#if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end
#parse("File Header.java")
/**
* <p>
* ${description}
* </p>
*
* @author 曹申阳
* @since ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}:${SECOND}
*/
public class ${NAME} {
}
可以自己按喜好修改。之后在新建类的时候会自动添加上类的注解。