总结之java代码规范（一）——注释规范、IDEA类和方法注释模板设置

最近新团队需要需要整一套适合java代码规范，基于阿里java开发手册规范一下代码规范。

（一）注释要求

1、【强制】类、类属性、类方法的注释必须使用javadoc规范，使用/*内容/格式，不得使用//xxx方式。

2、【强制】所有的抽象方法（包括接口中的方法）必须使用javadoc注释，除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

3、【强制】所有的类都必须添加创建者和创建日期。

4、【强制】方法内部单行注释在被注释语句上另起一行，使用//注释，方法内部多行注释使用/* */注释，注意与代码对齐。

5、【强制】所有的枚举类型必须要有注释，说明每个数据项的用途。

6、【推荐】在方法内部有优化项和需要多方面考虑的地方加上注释描述，方便后续迭代时思路恢复和充分考量。

7、【推荐】注释内容能够准确反映设计思路和代码逻辑；能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。

（二）注释注意事项

1、代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。

2、旧注释没有使用上述规范，如果涉及方法修复需要补充注释，并完善注释信息。

3、特殊注释标记，要注明标记人和标记时间。并且要及时处理这些标记，通过标记扫描，经常清理此类标记。

• 代办事宜（TODO）：表明需要实现但目前还未实现的功能。
• 错误（FIXME） ：表明某代码是错误的，而且不能工作，需要及时纠正。

（三）注释模板

IDEA提供注释模板，可以更方便我们生成注释
类注释模板：
1、File–>settings–>Editor–>File and Code Templates–>Files

我们选择Class文件（当然你要设置接口的还也可以选择Interface文件）
也可以使用如下，全局文件格式

javaDoc 标签

（1）@BelongsProject：当前项目的名称

（2）@BelongsPackage：当前包的名称

（3）@Author：作者姓名（可以写死，写成你的名字）

（4）@CreateTime：该类创建的时间

（5）@Description：对该类的描述（该类的功能）

（6）@Version：设置版本号，一般新创建的类都是1.0版本，这里写死就可以了

参数：

（1）${NAME}：设置类名，与下面的${NAME}一样才能获取到创建的类名

（2）TODO：代办事项的标记，一般生成类或方法都需要添加描述

（3）${USER}、${DATE}、${TIME}：设置创建类的用户、创建的日期和时间，这些事IDEA内置的方法，还有一些其他的方法在绿色框标注的位置，比如你想添加项目名则可以使用${PROJECT_NAME}

【推荐格式】

/**
* @Description: 
* @author liuxxxxx
* @date ${DATE} ${TIME}
*/

方法注释模板：
IDEA还没有智能到自动为我们创建方法注释，这就是要我们手动为方法添加注释 /**+Enter

1、File–>Settings–>Editor–>Live Templates

新建模板：命名为*

因为IDEA生成注释的默认方式是：/*+模板名+快捷键（比如若设置模板名为add快捷键用Tab，则生成方式为/*add+Tab）

点击模板页面最下方的警告，来设置将模板应用于那些场景，一般选择EveryWhere–>Java即可

（如果曾经修改过，则显示为change而不是define）

【推荐格式1】：无方法入参和返回值描述

**
* @Description $desc$
* @author liuxxxx
* @date $DATE$ $TIME$
**/

【推荐格式2】：有方法入参和返回值描述

**
 * @Description $desc$ $param$ $return$       
 * @author liuxxxxx
 * @date $DATE$ $TIME$
**/

配置变量

为了更趋向于javaDoc风格，可以配置 defatult value配置变量值格式化脚本

JavaDoc格式的需要自定义参数以及返回值的实现方式

获取参数实现方式：

groovyScript("def result = '';def params = \"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {if(params[i] != '')result+='* @param ' + params[i] + ((i < params.size() - 1) ? '\\r\\n ' : '')}; return result == '' ? null : '\\r\\n ' + result", methodParameters())

返回值实现方式：

groovyScript("return \"${_1}\" == 'void' ? null : '\\r\\n * @return ' + \"${_1}\"", methodReturnType())

使用： /*+Enter
效果：

/**
 * @Description  
 * @param id 
 * @return cn.com.xxx.DetailResponse       
 * @author liuxxxx
 * @date 2022/6/10 11:09
**/