在团队协作或长期维护的Java项目中，统一且清晰的代码注释是提升可读性和维护性的关键。IntelliJ IDEA 作为主流的 Java 集成开发环境，提供了强大的自定义模板功能，可以帮助我们自动化生成符合规范的注释。下面将详细讲解如何配置类与方法注释模板。
一、配置类注释模板
类注释的配置相对简单，通常在创建新类时自动生成。
-
打开 IDEA，进入 Settings (或 Preferences on macOS)。
-
导航至 Editor -> File and Code Templates。
-
选择右侧 Files 选项卡下的 Class。
-
在右侧的编辑框中，添加你希望的注释模板。例如，可以加入作者和日期信息：
/**
* @author yourName
* @date ${YEAR}-${MONTH}-${DAY} ${TIME}
*/
模板中 ${YEAR}, ${MONTH} 等是 IDEA 内置的变量，下方 Description 区域列出了所有支持的变量。
-
点击 Apply 或 OK 保存。此后，新建 Java 类时会自动添加此注释。若希望对接口生效，只需同步配置 Interface 项即可。
二、配置方法注释模板（支持智能参数与返回值）
方法注释的配置更为灵活，目标是实现：
- 根据方法形参自动生成
@param 注解。
- 根据方法是否有返回值智能生成
@Return 注解。
配置步骤如下：
-
创建模板分组：在 Settings 中进入 Editor -> Live Templates。点击右侧 + 号，选择 2. Template Group... 创建一个新分组，例如命名为 userDefine。
-
新建模板：选中刚创建的 userDefine 分组，再次点击 +，选择 1. Live Template。
-
编辑模板内容：
-
指定应用范围：点击模板下方 No applicable contexts yet 旁的 Define 链接，在弹窗中勾选 Java，表示此模板适用于所有 Java 文件。
-
编辑变量映射：模板文本中的 $date$、$param$ 等是自定义变量，需要为其指定表达式。点击 Edit variables... 按钮。
date: 在下拉框中选择 date()。time: 在下拉框中选择 time()。param: 需要自定义 Groovy 脚本来智能处理参数。粘贴以下代码：
groovyScript("def result = '';def params = \"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {if(params[i] != '')result+='* @param ' + params[i] + ((i < params.size() - 1) ? '\\r\\n ' : '')}; return result == '' ? null : '\\r\\n ' + result", methodParameters())
return: 同样需要自定义脚本来处理返回值。粘贴以下代码：
groovyScript("return \"${_1}\" == 'void' ? null : '\\r\\n * @return ' + \"${_1}\"", methodReturnType())
完成后点击 OK 保存所有设置。
三、效果演示
3.1 类注释
配置成功后，新建一个类时，IDEA会自动在类声明上方生成预设的注释。
3.2 方法注释
在方法内部任意行，输入 /** 然后按 Enter，即可触发模板生成方法注释。以下为各种情况的演示：
- 无形参
- 单个形参
- 多个形参
- 无返回值
- 有返回值
四、配置原理与常见问题 (Q&A)
Q1: 为什么缩写(Abbreviation)必须是 *，且展开键是Enter？*
A1: IDEA 的模板触发逻辑是 输入缩写 + 按下展开键。当缩写为 `，展开键为 Enter 时，我们在方法内先输入/，紧接着输入*并按下 Enter，即可触发模板。此时首行正好拼接成/**`，符合 Javadoc 规范。
*Q2: 模板中为何有一行空的 ``？**
A2: 这行通常用于填写方法的功能描述，是预留的空白行。如果不需要，可以将其从模板文本中删除。
Q3: $time$$param$ 为何紧贴在一起？
A3: 这是为了处理无参情况下的格式问题。自定义的 param 脚本在方法无参数时会返回 null，如果将 $time$ 和 $param$ 分在两行，当 $param$ 为 null 时，上一行会留下多余的尾随空格。将它们放在同一行，当 $param$ 为 null 时，该行内容会被完整移除，格式更整洁。
Q4: 为何 return 参数不使用内置的 methodReturnType()，而要自定义脚本？
A4: 内置的 methodReturnType() 在方法返回 void 时仍会返回字符串 "void"，这并非我们想要的。自定义脚本对其返回值进行了判断，仅在返回值类型非 void 时才生成 @return 标签。
Q5: 为何 $return$ 不单独成行？
A5: 原因同 Q3，是为了在方法返回 void (即 $return$ 为 null) 时，能干净地移除整行内容，避免留下空行或缩进格式问题。 | 
发表于 3 天前
|
查看: 8|
回复: 0
