IntelliJ IDEA注释模板配置指南：自动生成类与方法文档

一、配置类注释模板

打开 IntelliJ IDEA，进入 Settings (或 Preferences)，依次点击 Editor -> File and Code Templates。在右侧 Files 选项卡下选择 Class，在编辑框中添加以下模板内容：

/**
 * @author jitwxs
 * @date ${YEAR}年${MONTH}月${DAY}日 ${TIME}
 */

配置完成后，点击“OK”保存。此后，每当创建新的 Java 类时，IDEA 便会根据此模板自动生成类注释。若希望接口文件也应用此模板，只需对 Interface 选项卡进行相同配置即可。

二、配置方法注释模板

方法注释的配置相对复杂，目标是实现以下功能：

• 根据方法的形参数目自动生成 @param 注解。
• 根据方法是否有返回值，智能决定是否生成 @Return 注解。

具体配置步骤如下：

1. 进入 Settings -> Editor -> Live Templates。
2. 点击右侧的 + 号，选择 2. Template Group... 创建一个新的模板分组，命名为 userDefine（名称可自定义）。
3. 选中刚创建的 userDefine 分组，再次点击 +，选择 1. Live Template 创建一个新模板。
4. 配置该模板的关键属性：
   • Abbreviation: 必须设置为 *。
   • Description: 可填写描述，如“方法注释”。
   • Template text: 粘贴以下内容（注意首行无 /，且 * 顶格）：

     *
     *
     * @author jitwxs
     * @date $date$ $time$$param$ $return$

   • Expand with: 确保其值为 Enter (回车键)。
5. 点击模板配置区域下方的 Define，在弹出的上下文中勾选 Java，表示此模板适用于所有 Java 类型文件。
6. 点击 Edit variables 按钮，为模板中的变量（$date$， $time$ 等）设置对应的 Expression：
   • 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: 粘贴以下 Groovy 脚本（用于智能生成返回注释）：

7. 点击 OK 保存所有设置。

三、效果验证

3.1 类注释效果

新建一个类文件，IDEA 会自动在类定义上方生成配置好的注释模板。

3.2 方法注释效果

在方法内部输入 /** 并按 Enter，或直接输入 * 并按 Enter，即可触发模板生成方法注释。以下为不同情况下的生成效果演示：

• 无形参、无返回值的方法
• 单个形参、有返回值的方法
• 多个形参、有返回值的方法

四、配置原理与常见问题解答（Q&A）

*Q1: 为什么模板的 Abbreviation 必须设置为 `，且Expand with必须是Enter？** A1: IDEA 的模板触发逻辑是模板缩写 + 展开键。当展开键是Enter时，我们在方法内输入然后按Enter即可触发模板。同时，注释首行的会与之前输入的/结合，恰好形成符合 [Javadoc](https://yunpan.plus/f/28-1) 规范的/**` 开头。

*Q2: 模板文本中为何有一行独立的 ``？**
A2: 这行通常用于填写方法的功能说明，可根据个人习惯保留或删除。

Q3: 为什么 $time$$param$ 这两个变量紧贴在一起？
A3: 这是为了处理无参数时的退格问题。上述自定义的 param 脚本在无参数时会返回 null，若 $param$ 单独成行，则会留下一行空的 @param。将其与 $time$ 放在同一行，当无参数时，该行内容能正确退格清理。

Q4: 为什么 return 参数不使用内置的 methodReturnType()，而要自定义脚本？
A4: 内置的 methodReturnType() 在方法返回 void 时仍会返回 “void” 字符串。自定义脚本对其进行了判断，仅在方法有实际返回值时才生成 @return 标签，使注释更简洁。

Q5: 为什么 $return$ 没有单独成行？
A5: 原因同 Q3。为了确保当 methodReturnType() 返回 null（即无返回值）时，能正确处理格式，避免产生空行。