idea配置阿里格式化模板+注釋模板

水煮魚又失敗了

 

1 背景

本文意在將idea中的代碼格式和注釋格式進行統一化。

研發團隊的成員的代碼格式和注釋格式建議統一化。

統一的代碼格式和注釋格式，能給代碼閱讀上帶來極大的便利，給代碼改動上提高極大的效率。

1.1 開發工具

idea

1.2 代碼格式化模板

阿里格式化模板

1.3 注釋模板

（1）類模板樣例

/**
 * （自定義類描述）
 * @author zhangsan
 * @date 2020/09/08 08:23
 **/
public class MyTest {
}

 

（2）方法模板樣例

/**
 * （自定義方法描述）
 * @author zhangsan
 * @date 2020/09/07 20:07
 * @param message 
 * @param name 
 * @return java.lang.String 
 */
public String myTest(String message,String name){
    return "";
}

 

無參方法，將不生成@param參數：

/**
 * （自定義方法描述）
 * @author zhangsan
 * @date 2020/09/08 08:02
 * @return java.lang.String 
 */
public String myTest(){
    return "";
}

 

2 下載模板文件

阿里模板下載地址

https://github.com/alibaba/p3c/tree/master/p3c-formatter

下載如下兩個模板文件（鏈接為下載頁面）：

代碼格式（用於代碼格式化）：eclipse-codestyle.xml

代碼模板（代碼注釋模板，IDEA中無法使用）：eclipse-codetemplate.xml

3 IDEA代碼格式化

因阿里提供的代碼格式化配置是基於eclipse的，如需在idea中使用此配置，需要安裝對應的eclipse插件。

3.1 安裝插件

阿里配置文件是針對ecplice的，在IDE中，所有的配置文件導入，需要安裝Eclipse Code Formatter插件。

3.2 配置代碼格式

File->Settings->Other Settings->Eclipse Code Formatter進行idea代碼格式配置：

將代碼格式化文件eclipse-codestyle.xml，配置到插件中：

 

eclipse代碼格式化配置.png

3.3 使用

（1）格式化部分代碼

選中需要格式化的代碼，快捷鍵：ctrl+alt+L

（2）格式化整個文件

在需要格式化的文件中，快捷鍵：ctrl+alt+L

（3）格式化整個項目（慎用）

idea中，項目上右鍵->Reformat Code

如已經存在的項目初次使用統一的代碼格式化，建議在一個時間點將整個項目統一進行一次代碼格式化。避免單獨的格式化，導致部分研發人員的代碼合並出現嚴重沖突。

4 IDEA代碼注釋配置

4.1 配置全局中USER

在此配置全局USER，用於填充自動生成的注釋中的作者@author屬性。

Help->Edit Custom VM Options...

增加如下配置：

-Duser.name=xxx

 

4.2 配置類注釋模板

settings->Editor->File and Code Templates->files->class

 

class模板.png

增加注釋模板：

/**
 * ${description}
 * @author ${USER}
 * @date ${YEAR}/${MONTH}/${DAY} ${HOUR}:${MINUTE}
 **/

 

模板增加后，如下（注釋上方的換行符必須有）：

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


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

 

新創建java文件時，會提示輸入類描述description，生成的文件格式如下：

package com.test;

/**
 * 我的測試類
 * @author zhangsan
 * @date 2020/09/08 10:23
 **/
public class MyTest {
}

 

4.3 配置方法注釋

4.3.1 配置流程

Editor->Live Template->java

新建Live Template，進行如下配置：

 

配置方法模板流程.png

第5步，適用場景配置如下：

 

模板適用場景.png

第6步，模板變量配置如下：

 

模板變量配置.png

4.3.2 配置參數

（1）模板配置

配置如下：

縮寫Abbreviation：

*   

 

模板Template text：

*
 * 
 * @author $user$
 * @date $data$ $time$$param$
 * @return $return$ 
 */

 

（2）變量配置

user：

user()

 

date：

date("yyyy/MM/dd")

 

time：

time("HH:mm")

 

param：

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

 

return：

methodReturnType()

 

4.3.3 使用

在java方法上輸入/**后，按下tab鍵，即可在方法上方生成方法注釋，如下：

/**
 * （①方法描述）
 * @author zhangsan
 * @date 2020/09/07 20:07
 * @param message （②參數描述）
 * @param name （②參數描述）
 * @return java.lang.String （③返回值描述）
 */
public String myTest(String message,String name){
    return "";
}

 

依次填寫：

①方法描述
②參數描述
③返回值描述

4.3.2 注意事項

（1）為避免對變量注釋時的影響，變量的注釋仍然采用默認的注釋方式：/**+回車，生成的注釋仍然是默認注釋：

/**
 * 
 */
private String userName;

 

（2）無參方法，將不生成@param參數：

/**
 * 
 * @author zhangsan
 * @date 2020/09/08 08:02
 * @return java.lang.String 
 */
public String myTest(){
    return "";
}

 

4.4 補充（關於類注釋）

4.2中，配置的類注釋模板，需要在創建類的時候，才可以生成類注釋。對於拷貝過來的類文件，或者已經存在的類文件，無法加上對應注釋。

因此，可以參照4.3，進行代碼模板配置。

4.4.1 配置流程

 

類模板.png

其中的5 適用場景同4.3.1：

 

模板適用場景.png

4.4.2 配置參數

（1）模板配置

配置如下：

縮寫Abbreviation：

cc  

 

模板Template text：

/**
 * 
 * @author $user$
 * @date $date$ $time$
 **/

 

（2）變量配置

user：

user()

 

date：

date("yyyy/MM/dd")

 

time：

time("HH:mm")

 

description：

不配置

4.4.3 使用

在類上輸入cc后，按下回車鍵，即可在方法上方生成類注釋，如下：

/**
 * （①類描述）
 * @author zhangsan
 * @date 2020/09/08 08:21
 **/
public class MyTest {
}

 

填寫：

①類描述