Intellij IDEA 最佳实践-注释模板

IDEA 的设置项中提供了 Live Templates 和 File and Code Templates 的设置。其中：

Live Templates 用于配置方法注释模板和代码模板，这类模板需要在写代码的过程中通过关键字手动触发；
File and Code Templates 用于配置文件模板，新建文件时 IDEA 会自动填入我们配置的模板内容。常用于配置类注释、接口注释等。

Live Templates

借助 IDEA 的 Live Templates 功能，我们可以实现代码模板和注释模板的配置。

Live Templates 设置页面的路径为：“File” -> “Settings” -> “Editor” -> “Live Templates”。

模板组

IDEA 的 Live Template 中有模板组（Template Group）和模板（Live Template）两个概念。Live Template 模板以分组的形式存在于 Template Group 之下。

新建模板组的步骤非常简单：

点击 Live Templates 面板右方的 + 号并选择 “Template Group” ；
在弹出的输入框中输入模板组名称，点击 ”OK” 确认；

方法注释模板

在 Live Templates 面板选择自己刚刚新建的模板组；
点击面板右侧的 + 号并选择 “Live Template” 新建模板；

填写方法模板信息：

在 ”Abbreviation” 输入框写入 m，这里是模板的简写，也可以叫做触发模板的关键字；
在 “Description” 输入框写入 方法注释，这里写入的是模板描述，方便我们自己确认模板功能；
在 ”Template text” 文本框写入以下模板：
1
2
3
4
5
6
**
* $description$
* $params$ $returns$
* @author $user$
* @date $date$ $time$
*/
可以看到，我们在模板中定义了许多变量。

点击 “Edit variables” 并填写变量表达式：

idea-settings-editor-live-templates-edit-variables

在 ”params” 后的 “Expression” 输入框填入以下内容并勾选 ”Skip if defined“ 复选框：

groovyScript(
    "def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); 
        def result='';
        for(i = 0; i < params.size(); i++) {
            if (params[i] == '') {
                continue;
            };

            result += '\\n * @param ' + params[i];
        }; 
        return result == '' ? '' : result", 
    methodParameters()
)

这段 groovy 脚本的作用是生成参数注释。

勾选 ”Skip if defined“ 复选框的作用是如果表达式已经为对应变量生成了值，那么就跳过手动输入步骤。

在 ”returns” 后的 “Expression” 输入框填入以下内容并勾选 ”Skip if defined“ 复选框：
1
2
3
4
5
groovyScript(
"def returnType = \"${_1}\";
return returnType == 'void' ? '' : '\\n* @return ' + returnType + ''",
methodReturnType()
)
这段 groovy 脚本的作用是生成i返回值注释。
在 ”user” 后的 “Expression” 输入框填入 user() 并勾选 ”Skip if defined“ 复选框；

这里的 user() 是 IDEA 内置的方法，取当前操作系统登录用户的账号。此处也可以为固定字符串，取值为自己想要展示在方法注释中的名字。
在 ”date” 后的 “Expression” 输入框填入 date("yyyy-MM-dd") 并勾选 ”Skip if defined“ 复选框；
在 ”time” 后的 “Expression” 输入框填入 time("HH:mm:ss") 并勾选 ”Skip if defined“ 复选框；
点击 ”OK“ 确认变量设置；

配置可选项：
- 把页面上方 ”By default expand with” 和页面右下角 “Options” 栏中的 ”Expand with” 设置为 “Tab”;
  
  Live Template 的触发方式为关键词 ”Abbreviation” + “Expand with”。
  
  按照我们上面的设置，如果想插入方法注释，只需要在方法上面一行输入 m 然后下 Tab 键，IDEA 就会把我们设置好的 “Template text” 插入到代码中。
- 勾选页面右下角的 ”Reformat according to style”， IDEA 会在我们插入代码模板后自动根据当前设置的代码风格将其格式化；
- 勾选页面右下角的 “Shorten FQ names”，IDEA 会自动截断完整标识符并导入对应语句；
配置适用范围：

点击页面左下角的 “Define” / “Change” 并在弹出面板中选择 ”Java”，表示此模板只会在 Java 文件中生效。
至此，配置完成。

看下效果：

这里之所以在关键字 m 前加了斜线 / 是因为我在模板文字中没有写注释的斜线 /。添加 / 之后，注释才能完整。

举一反三

属性/成员变量注释模板

属性 / 成员变量注释模板如图所示，此处不再赘述。

构造器注释模板

构造器注释模板相对于方法注释模板只是删除返回值：

SpringBootTest 注解模板

SpringBootTest 注解模板如图所示：

原生模板

IDEA 也预置了许多代码模板，以 Java 为例：

sout 可以生成 System.out.println() 语句；
fori 可以生成 for 循环；

此处不一一列举，感兴趣的话还请自行查看。

File and Code Templates

File and Code Templates 用于配置文件模板，新建文件时 IDEA 会自动填入我们配置的模板内容。常用于配置类注释、接口注释等。

Files

这里可以对文件和代码模板进行配置，其中：

“Description” 栏罗列了 IDEA 预置的变量，可以自行选择组合使用。

Class

Class 可以对 Java 的类模板进行配置：

在模板输入框填入以下内容：

#if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end
#parse("File Header.java")

/**
 * ${NAME}
 *
 * @author ${USER}
 * @date ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}
 */
public class ${NAME} {
}

idea-settings-editor-file-and-code-templates-class

之后新建的 Java Class 文件会自动填充携带有 @author 和 @data 的 Java Doc 注释：

new-interface-with-java-doc

Interface

Interface 配置页可以对 Java 的接口模板进行配置。

在模板输入框填入以下内容：

#if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end
#parse("File Header.java")
/**
 * ${NAME}
 *
 * @author ${USER}
 * @date ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}
 */
public interface ${NAME} {
}

idea-settings-editor-file-and-code-templates-interface

之后新建的 Java Interface 文件会自动填充携带有 @author 和 @data 的 Java Doc 注释：

new-java-class-with-java-doc

题外话

最近花了一周时间系统整理了 Intellij IDEA 的最佳实践，内容涵盖了基础配置、原生能力和精选插件几个模块。

地址为: idea.diqigan.cn，相信会对你有所帮助。