Idea 配置 Java 方法注释

西红柿蛋炒饭
905 阅读3分钟

「这是我参与11月更文挑战的第7天，活动详情查看：2021最后一次更文挑战」

前言

各种 Java 规范中对于注释的规范都有一定的要求，在编写代码时对于类、方法的注释其实很多时候都有固定的模板。 对于 Idea 自动生成方法注释的文章其实有很多，但是很多教程会存在奇奇怪怪的问题导致配置失败。所以就记录一个配置的过程。

正文

注释的重要性

注释背景：

  • 第一次接触一段代码如何快速获取有效信息？
  • 怎么样避免注释冗长而且凌乱不堪呢？
  • 多人协同开发，我们要怎样高效沟通愉快合作呢？

注释意义：

  • 提高晦涩难懂的代码的可读性
  • 隐藏代码复杂细节
  • 改善系统的设计

关于注释的重要性不言而喻，简单的来说一个团队应该有着自己对于注释的相关规范，然后团队成员遵循规范愉快开发。下面就记录一下关于 Idea 中关于注释的一些配置，具体的模板需要根据团队的规则配置。

方法注释

环境介绍

  • 硬件：Mac-2020
  • 软件：IntelliJ IDEA Ultimate 2020.3.4

详细配置

  1. 功能实现介绍：
  • 根据形参数目自动生成 @param 注解
  • 根据方法是否有返回值智能生成 @Return 注解
  1. 配置路径

Settings（Preferences） -> Editor –> Live Templates -> Java

  1. 配置过程

在 Java 的 Template Group 中创建新的 Live Template

注意：关于模板的配置很多文章说开头不需要 /* ，但是我配置确是需要的，可能是版本的问题。

详细的配置如下图： image.png

  • Abbreviation：设置模板名称，建议就是 * 号（如图配合 Tab 可以自动生成注释 ）
  • Description：模板描述
  • Template text：详细模板配置

对应 Template text 模板配置如下：

/**
 * @Description: $END$
 * @Author: $user$
 * @Date: $date$ $time$
 $param$
 $return$
 **/

参数配置如下：

image.png

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

# return  groovy 脚本
groovyScript("def returnType = \"${_1}\"; def result = '* @return: ' + returnType; return result;", methodReturnType());

# methodParameters 返回参数脚本（用于校验）
groovyScript("return \"${_1}\";", methodParameters());

脚本解释

由于没有找到合适的 Groovy 格式化工具，手动格式化部分代码。如果您发现你复制的代码不能达到你想要的效果，可以跟我一样格式化代码之后缝缝补补即可。

代码的逻辑很简答：

  • 获取方法参数字符串
  • 格式化参数字符串切成数组
  • 遍历数组构造新的返回参数
// ${_1} 参数类似 [param1,param2]

if(\"${_1}\".length() == 2) {
   return '';
} 
else {
	def result=''; 
        // 替换不必要的字符
	def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList();
	for(i = 0; i < params.size(); i++) {
            // 拼接返回参数
            if(i==0){
                result+='* @param ' + params[i] + ': '
            }else{
                result+='\\n' + ' * @param ' + params[i] + ': '
            }
	}; 
	return result;
}

注释效果

如图 在方法内部通过 * + Tab 自动生成的方法注释，使用者只需要手动输入方法的描述以及各参数的描述。

image.png

总结

  1. 其他文档中关于 Groovy 脚本部分会出错，可以通过简单的调试、修改达到目的。语法很简单，如果只是修改逻辑基本没有学习成本。

  2. Live Template 中有很多快捷方式，可以当作文档查看，比如： psvm sout

image.png

  1. 可以自定义其他的快捷方式，具体的实现方式可以参考已有的快捷方式
avatar
文章
阅读
粉丝