前言
实际团队协作开发过程中,经常会遇到代码风格不一致导致的文件合并冲突问题。这里的风格不一致,大致包含以下几个方面:
- 注释风格(本章介绍:使用intellij idea的Code Templates功能来规范)
- 代码缩进、换行等风格(需另起文章介绍:使用Eclipse Code Formater插件来规范)
- 命名风格(需另起文章介绍:使用CheckStyle-IDEA插件来规范)
注释风格有主要分为 文档注释、类注释、方法注释 等3个方面,一下逐个介绍。
文档注释
主要包含文档头(默认)、文档尾、自定义(常用)三类,此节主要介绍常用的文档头和自定义两类。
- 文档头:主要用于生成对java类、接口、枚举、etc.的说明模板,目的是统一注释风格,方便代码维护和审阅。
- 自定义:常见的用法是自动生成源代码的版本归属和说明。
intellij idea的设置路径:File => Settings => Editor => File and Code Templates
步骤一
- 主要关注Class、Interface、Enum三个配置即可。
步骤二
- 由上图可以看出默认是通过解析 File Header.java 文件实现文件注释的,添加阿里规约的类注释说明。
注释代码如下:/** * 描述: * * @author zangh * @date ${DATE} ${TIME} */
步骤三
- 添加自定义的版权归属文档描述,新增CopyRight Header.java文件。
版权注释如下:// +---------------------------------------------------------------------- // | springboot 微服务框架 [ JavaWeb ] // +---------------------------------------------------------------------- // | 版权所有: 2022 ejy365 // +---------------------------------------------------------------------- // | 官方网站: https://www.ejy365.com/ // +---------------------------------------------------------------------- // | 版本声明: // | 本软件框架禁止任何单位和个人用于任何违法、侵害他人合法利益等恶意的行为,禁止用于任何违 // | 反我国法律法规的一切平台研发,任何单位和个人使用本软件框架用于产品研发而产生的任何意外 // | 、疏忽、合约毁坏、诽谤、版权或知识产权侵犯及其造成的损失 (包括但不限于直接、间接、附带 // | 或衍生的损失等),本团队不承担任何法律责任。本软件框架只能用于公司和个人内部的法律所允 // | 许的合法合规的软件产品研发,详细声明内容请阅读《框架免责声明》附件; // +----------------------------------------------------------------------
步骤四
- 在Class、Interface、Enum中添加#parse(“CopyRight Header.java”)头部。
- 尝试新建ParallelStreamTest.java文件,下图为自动生成的效果:
类注释
通常我们对新建的类文件添加注释,文档注释 > 文档头 的注释即可。
如果我们希望对于已经存在的类文件,可以通过以下方式:
intellij idea的设置路径:File => Settings => Editor => Live Templates
注释配置
步骤一
- 添加模板组:Live Templates => Template Group… => 添加组名为Ejy365
步骤二
- 添加Live Template
注释代码如下:** * 描述: * * @author zangh * @date $date$ $time$ */
- 配置注释变量对应的函数
注释作用域
- 作用域,我们只选择比较关心的java相关文档格式:
测试效果
- 实际操作效果如下,与通过头文档方式生成的保持了一致
方法注释
注释配置
步骤一
- 与类注释一致(如果已经存在Ejy365则跳过此步骤)
步骤二
-
添加Live Template
注释代码如下:** * 描述: * $param$ * $return$ */
-
配置注释变量对应的函数
param变量表达式:
groovyScript("def result=''; def stop=false; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); if (params.size()==1 && (params[0]==null || params[0]=='null' || params[0]=='')) { stop=true; }; if(!stop) { for(i=0; i < params.size(); i++) {result +=((i==0) ? '\\r\\n' : '') + ((i < params.size() - 1) ? ' * @param ' + params[i] + ': \\r\\n' : ' * @param ' + params[i] + ': ')}; }; return result;", methodParameters())
return变量表达式:
groovyScript("def result=''; def data=\"${_1}\"; def stop=false; if(data==null || data=='null' || data=='' || data=='void' ) { stop=true; }; if(!stop) { result += '\\r\\n' + ' * @return ' + data; }; return result;", methodReturnType())
注释作用域
- 作用域,与类注释一致
测试效果
- 分别测试有无入参,有无返回值等情况