【效率提升】自定义配置IDEA中的Java注释模板

1.背景

由于在公司的编码规约中关于注释的规约，在IDEA中的默认模板无法适配，所以在每次新建接口、类、方法的时候都需要手动的修改注释。为了避免这个重复的工作就需要将IDEA中的注释模板修改一下，本篇参考了一些网络上的配置方法，这里总结一下。

2.模板配置

主要需要配置的是类模板与方法模板，下面会写一下配置的方法，以及使用上需要注意的问题。

2.1.配置类模板

在IDEA中找到如下的路径，配置文件模板：

File > Settings > Editor > File And Code Templates

首先是在，includes中找到File Header这个配置模板，如果没有的话就新建一个同名文件，然后再右侧的编辑区域写上@author和@date。
其中作者可以像我这样写死，也可以使用下面提示的${USER，但后面这种方式会默认使用操作系统的名字（如：Administrator）。
日期的配置可以参考右下角的Description中的变量模板，一般只需要配置$DATE，我这里由于习惯问题也加上了${TIME}

---

第二步是切换到Files中，找到Java相关的几个文件类型，在右侧的#parse那里加上刚刚修改的模板文件的文件名，但这里一般默认就是File Header.java，不需要修改，如果你创建了其他的模板，就可以考虑在这里修改一下引用。

---

配置完成之后创建一个新的类，效果如下（接口或者枚举也是一样的效果）：

2.2.配置方法模板

接下来是方法模板，在不配置模板的时候使用IDEA的自定义模板是这样的：

现在同样的想给加上作者和日期，可以按如下的配置，首先还是找到配置路径：

File > Settings > Editor > Live Template

2.2.1. 创建自定义模板分组

先试用Template Group创建一个模板分组，写一个好听的名字，然后选中刚刚创建好的分组通过List Template创建一个模板。

2.2.2. 配置缩写、模板、触发键

缩写abbreviation的意思就是在IDEA的代码编辑页中使用这个缩写，再加上触发键就可以生成对应的模板代码，例如大家都用过的psvm+回车键，可以生成main方法。

在这里我们将缩写配置为**，因为我们在编写文档注释的时候，会在方法上先打出/**，这里的两个星号当做缩写就比较自然。

下面的模板配置没有第一个/，这是因为在触发键触发后，缩写中的**会被模板替代掉，但是/不会，如果模板中配置了/，生成后则会变成//**。
另外，如果是常量直接写死即可，如果是变量则可以写成$xxx$的方式，变量值的配置会在下面的2.2.3 部分去讲。

**
 * 功能描述
 *
 * $param$
 * @return $retrun$
 * @author 挥之以墨
 * @date $date$ $time$
 */

---

然后是触发键，在右侧的Option中，选择Tab或保持Default（Tab）也行，这里之所以不选择使用Enter是因为使用/**给字段创建注释的时候不需要这一堆模板的信息，只需要一个简单的文档注释说明字段是什么含义。
如果使用了Enter那么原有的默认生成注释的方式就会被覆盖掉，给字段写注释时，也会自动生成上面配置的模板信息，然后再手动删掉，非常麻烦。

---

最后是使用范围，在Applicable下面点击change，选择Java > Comment即可。

2.2.3. 变量配置

我们在上面的模板中定义了4个变量，可以通过右侧的Edit Variables来编辑变量值：


其中，下面三个直接使用IDEA自带的表达式即可：

• return：methodReturnType()，也可以不要这个表达式，保持为空
• date：date()
• time：time()

param参数是一个重点，我在IDEA中没有找到合适的表达式，其中最适合的一个表达式是methodParameters()，这个表达式会按照参数的名字生成一个数组，就像这样：

所以在这里使用了一个groovy脚本来生成对应的@param注释，我们可以将得到的[name, age]值拆解一下，然后在编辑变量里面的Default Value中填入：

groovyScript("if(\"${_1}\".length() == 2) {return '';} else {def result=''; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList();for(i = 0; i < params.size(); i++) {if(i==0){result+='@param ' + params[i] + ' '}else{result+='\\n' + ' * @param ' + params[i] + ' '}}; return result;}", methodParameters());

---

接下来对上面的脚本做一下解释，下面是格式化后的脚本：

groovyScript(
    """
    if ("${_1}".length() == 2) {
        return ''
    } else {
        def result = ''
        def params = "${_1}".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList()
        
        for (i = 0; i < params.size(); i++) {
            if (i == 0) {
                result += '@param ' + params[i] + ' '
            } else {
                result += '\\n' + ' * @param ' + params[i] + ' '
            }
        }
        return result
    }
    """,
    methodParameters()
)

首先，methodParameters()函数会传入一个数组（字符串），${_1}就是表示这个数组的引用。

• 第一步："${_1}".length() == 2其实就是在判断是否传入了一个空数组[]（即方法没有入参）。
• 第二步：.replaceAll和split(',')就是把这个字符串重新转换成数组结构
• 第三步：i==0表示第一个参数，拼接起来就好，i>1时，需要换行并拼接一个*号。

---

最后看一下效果吧，在方法中输入/**并按tab键，生成方法注释：

3.总结

本篇讲解了如何配置类的注释模板和通过代码模板来配置方法注释模板，需要注意缩写、模板、触发键、变量的配置。
其中，变量可以使用IDEA中内置的表达式来匹配变量值，当默认的表达式不满足要求时，也可以使用groovy脚本来做一个自定义的函数表达式满足需求。后续如果想要配置其他自定义模板时，也可以参考这套配置方法。