笔记【intellij idea + alibaba注释规约模板】

• • • 前言
    • 文档注释
    • • 步骤一
      • 步骤二
      • 步骤三
      • 步骤四
    • 类注释
    • • 注释配置
      • • 步骤一
        • 步骤二
      • 注释作用域
      • 测试效果
    • 方法注释
    • • 注释配置
      • • 步骤一
        • 步骤二
      • 注释作用域
      • 测试效果
    • 参考文档

实际团队协作开发过程中，经常会遇到代码风格不一致导致的文件合并冲突问题。这里的风格不一致，大致包含以下几个方面：

1. 注释风格（本章介绍：使用intellij idea的Code Templates功能来规范）
2. 代码缩进、换行等风格（需另起文章介绍：使用Eclipse Code Formater插件来规范）
3. 命名风格（需另起文章介绍：使用CheckStyle-IDEA插件来规范）

注释风格有主要分为 文档注释、类注释、方法注释 等3个方面，一下逐个介绍。

主要包含文档头_（默认）、文档尾、自定义_（常用）三类，此节主要介绍常用的文档头和自定义两类。

1. 文档头：主要用于生成对java类、接口、枚举、etc.的说明模板，目的是统一注释风格，方便代码维护和审阅。
2. 自定义：常见的用法是自动生成源代码的版本归属和说明。

intellij idea的设置路径：File => Settings => Editor => File and Code Templates

• 主要关注Class、Interface、Enum三个配置即可。
  

• 由上图可以看出默认是通过解析 File Header.java 文件实现文件注释的，添加阿里规约的类注释说明。
  
  注释代码如下：

• 添加自定义的版权归属文档描述，新增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())
  

• 作用域，与类注释一致

• 分别测试有无入参，有无返回值等情况
  

alibaba 注释规约模板