日常开发中，如何规范使用注释

曹申阳

于 2024-08-20 13:43:18 发布

阅读量422

点赞数 9

分类专栏： JAVA基础文章标签： java idea

本文链接：https://blog.csdn.net/qq_34709175/article/details/141356159

版权

JAVA基础专栏收录该内容

3 篇文章 0 订阅

订阅专栏

前言

任何一门语言，都有自己的注释标准，注释的作用就是解释说明程序的文字。
Java中的注释类型有三种：

单行注释 //
多行注释 /**/
文档注释 /** */

一、在项目中如何规范使用注释？

单行注释
1. 当代码意义不够明显，在当前代码片段上一行添加注释来解释代码作用
2. 一般用在方法内部

// Add boot specific singleton beans
ConfigurableListableBeanFactory beanFactory = context.getBeanFactory();

多行注释
1. 基本是用不到，不常用，如果出现大篇幅的注释，那么你这段代码可能需要重新梳理一下逻辑了，重构了。
文档注释
1. 一般在类、方法的上一行添加注释，来解释其功能、参数和返回值等

/**
 * 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) {
    ...
}

使用规范
1. 不要保留已经不再适用的旧代码注释
2. 不要每行都写注释，一些方法名、变量名需要见名知意，包含一定的语义，只有复杂逻辑才需要。
3. 修改代码逻辑时，要同步修改注释，不要造成欺骗😭

二、一些常用注释技巧

以下都是基于 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} {
}