Java注释相关以及IDEA配置相关的注释

本文章主要包括以下6个内容：

一、注释分类以及javadoc的使用

二、使用Alibaba Java Coding Guidelines规范编码。

三、IDEA配置类注释

四、IDEA配置方法注释

====================正文开始====================

---

一、注释分类以及javadoc的使用。

　　所谓注释就是只给人看的，而并不会被执行的语句。适当的代码注释可以提高代码可读性，也方便后期的维护，所以在编程初期就要养成良好的编码习惯。代码注释分为一下三种：

　　1、单行注释：      // ……单行注释。

　　2、多行注释：     /* ...... */ 多行注释，注释内容不会出现在javadoc 生成的文档中。

　　3、文档注释 :        /** ...... */ 多行注释，注释内容写入javadoc生成的文档。

 

 这三种注释的具体使用可使用Alibaba Java Coding Guidelines插件进行学习。详见第二大点。

　　3.1javadoc生产API文档

　　可参见官方文档：https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html

　　这里对Two.java文件进行生产API文档

　　Two.java文件的文件内容为：

/**
 * @author ThreePure
 * @date 20/9/16 8:52
 * @description:输出Hello World
 * @since 1.8
 */
public class Two {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}

 

　　在java文件中运行cmd命令行窗口，执行：javadoc -encoding UTF-8 -charset UTF-8 Two.java

 

 　　生成后文件内容为

　　 这里打开index.html文件就可以查看产生的API文档。

 

二、使用Alibaba Java Coding Guidelines规范编码。

　　2.1了解什么是Alibaba Java Coding Guidelines？

　　Alibaba Java Coding Guidelines是阿里巴巴于2017年10月14日在杭州云栖大会上，正式发布众所期待的《阿里巴巴Java开发规约》扫描插件！该插件由阿里巴巴P3C项目组研发。P3C是世界知名的反潜机，专门对付水下潜水艇，寓意是扫描出所有潜在的代码隐患。这个项目组是阿里巴巴开发爱好者自发组织形成的虚拟项目组，把《阿里巴巴Java开发规约》强制条目转化成自动化插件，并实现部分的自动编程。

　　简单的说就是一个编程时的规则，使代码更加的美观可读。特别是对呀一些编程小白，能够从一开始就养成良好的编程习惯。

　　阿里巴巴基于手册内容，研发了一套自动化的IDE检测插件（IDEA、Eclipse）。该插件在扫描代码后，将不符合规约的代码按Blocker/Critical/Major三个等级显示在下方。甚至在IDEA上，还基于Inspection机制提供了实时检测功能，编写代码的同时也能快速发现问题所在。对于历史代码，部分规则实现了批量一键修复的功能。极大的提高了代码质量。

　　2.2 在IDEA中安装Alibaba Java Coding Guidelines Plugins 。

 　　安装完成后有多种方式使用。

 　　点击编码规约扫描，扫描结果可能出现类似下图的结果：

 　　根据bug的严重程度，优先级定义了Blocker,Critical,Major，Minor/Trivial几个等级。单击即可查看相应的规则和建议。

　　归于新手而言最好的功能还是它能实时地检查你书写的代码，并且在右侧实时给出警告，而且警告也是汉字。在你书写的代码中只要存在不符合规范的地方就会用黄色的波浪线显示出来，当鼠标放上去，就会显示相应的提示信息。

　　阿里规范代码已经开源，GitHub：https://github.com/alibaba/p3c

三、IDEA配置类注释

 　　我的内容是：

/**
 * @author username
 * @date ${DATE} ${TIME}
 * @since 1.8
 * @description:TODO
 */

 

设置完成后在以后每次新建类时都会自动产生该注释。

四、IDEA配置方法注释

　　方法注释的设置跟类注释基本一致。打开Settings=》Editor=》Live Templates。选择右侧的+号，选择Templates Group。

 　　弹出一下窗口，输入想要的组名即可：

　　2，选择刚刚建好的组，点击右侧+号，点击Live Template

 

 　　创建一个新的模板：

　　　　Abbreviation：是缩写的意思，也就是在需要产生这个注释的地方输入这个内容，摁下回车（也可以根据By default expand with属性选择其他键），就可以产生注释。建议越短越好。

　　　　Description：添加一个描述信息，只是为了方便知道这个缩写用来干嘛的。

T　　　　emplate text：输入模板。这里特别注意当输入一个变量时，比如图中的date，time，param以及return，这些是变化的，当IDEA识别到输入了变量时，需要在右边的Edit variables中添加函数才能有效。注意这里需要区别设置类方法时的{DATE}，这里不需要{}。

　　我这里设置模板内容为：

/**
 * @author username
 * @date $date$ $time$
 * @description:
 * @Param:$param$
 * @Return:$return$
 */

 

 　　Expression具体设置参照下图

 

 　　这里解释一下param和return两个变量，param是指参数，也就是这个方法会有哪些参数，return是指返回类型。但是需要自动产生这两个值，就必须在方法内部使用。如果在方法外部使用，将无法获得这两个参数。