跳至主要內容

JAVA格式化模板+注释模板

知识库项目管理代码规范代码规范大约 4 分钟

1 背景

  • 本文意在将idea中的代码格式注释格式进行统一化。
  • 研发团队的成员的代码格式和注释格式建议统一化
  • 统一的代码格式注释格式,能给代码阅读上带来极大的便利,给代码改动上提高极大的效率。

2 注释模板

(1)类模板样例

/** 
 * (自定义类描述)
 * @author dong.zhao
 * @date 2023/03/21 21:00
 */
public class MyTest {}

(2)方法模板样例

/**
 * (自定义方法描述)
 * @author dong.zhao
 * @date 2023/03/21 21:00
 * @param message
 * @param name
 * @return java.lang.String
 */
public String myTest(String message, String name){
    return "";
}

(3)无参方法模板样例

/**
 * (自定义方法描述)
 * @author dong.zhao
 * @date 2023/03/21 21:02
 * @return java.lang.String 
 */
public String myTest(){
    return "";
}

3 下载模板文件

阿里模板下载地址: https://github.com/alibaba/p3c/tree/master/p3c-formatteropen in new window

下载如下两个模板文件(链接为下载页面):

  • 代码格式(用于代码格式化):eclipse-codestyle.xml
  • 代码模板(代码注释模板IDEA中无法使用):eclipse-codetemplate.xml

4 IDEA代码格式化

因阿里提供的代码格式化配置是基于eclipse的,如需在idea中使用此配置,需要安装对应的eclipse插件

(1)安装插件

阿里配置文件是针对ecplice的,在IDE中,所有的配置文件导入,需要安装Eclipse Code Formatter插件。

(2) 配置代码格式

File->Settings->Other Settings->Eclipse Code Formatter进行idea代码格式配置:

将代码格式化文件eclipse-codestyle.xml,配置到插件中:

图片
图片

(3) 使用格式化

  • 格式化部分代码

选中需要格式化的代码,快捷键:ctrl+alt+L

  • 格式化整个文件

在需要格式化的文件中,快捷键:ctrl+alt+L

  • 格式化整个项目(慎用)

idea中,项目上右键->Reformat Code

如已经存在的项目初次使用统一的代码格式化,建议在一个时间点将整个项目统一进行一次代码格式化。避免单独的格式化,导致部分研发人员的代码合并出现严重冲突。

5 IDEA代码注释配置

(1)配置全局中USER

在此配置全局USER,用于填充自动生成的注释中的作者@author属性。

Help`->`Edit Custom VM Options...

增加如下配置:

-Duser.name=dong.zhao

(2) 配置类注释模板

settings`->`Editor`->`File and Code Templates`->`files`->`class
图片
图片

增加注释模板:

/**
 * ${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 dong.zhao
 * @date 2023/03/21 21:00
 */
public class MyTest {
}

(3)配置方法注释

5.3.1 配置流程

`Editor`->`Live Template`->`java`

新建Live Template,进行如下配置:

图片
图片

第5步,适用场景配置如下:

图片
图片

第6步,模板变量配置如下:

图片
图片

5.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()

5.3.3 使用

在java方法上输入/**后,按下tab键,即可在方法上方生成方法注释,如下:

/**
 * (①方法描述)
 * @author dong.zhao
 * @date 2023/03/21 21:00
 * @param message (②参数描述)
 * @param name (②参数描述)
 * @return java.lang.String (③返回值描述)
 */
public String myTest(String message,String name){
    return "";
}

依次填写:

①方法描述
②参数描述
③返回值描述

5.3.4 注意事项

(1)为避免对变量注释时的影响,变量的注释仍然采用默认的注释方式:/**+回车,生成的注释仍然是默认注释:

/** */
private String userName;

(2)无参方法,将不生成@param参数:

/**
 * 
 * @author dong.zhao
 * @date 2023/03/21 21:00
 * @return java.lang.String 
 */
public String myTest(){
    return "";
}

(4) 补充(关于类注释)

5.2中,配置的类注释模板,需要在创建类的时候,才可以生成类注释。对于拷贝过来的类文件,或者已经存在的类文件,无法加上对应注释。

因此,可以参照5.3,进行代码模板配置。图片

其中的5 适用场景同4.3.1:图片

5.4.1 配置参数

(1)模板配置

配置如下:

缩写Abbreviation:

cc

模板Template text:

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

(2)变量配置

user:

user()

date:

date("yyyy/MM/dd")

time:

time("HH:mm")

description:

不配置

5.4.2 使用

类上输入cc后,按下回车键,即可在方法上方生成类注释,如下:

/**
 * (①类描述)
 * @author dong.zhao
 * @date 2023/03/21 21:00
 */
public class MyTest {
}

填写:

①类描述