前言
任何一门语言,都有自己的注释标准,注释的作用就是解释说明程序的文字。
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} {
}
可以自己按喜好修改。之后在新建类的时候会自动添加上类的注解。
如果这篇文章对您有帮助,非常欢迎您点赞支持!
这不仅是对我的认可,也能鼓励我继续创作更多有价值的内容。
感谢您的支持和反馈,希望未来还能为您提供更多有益的信息和灵感。