工欲善其事，必先利其器！

个人以为，写代码不加注释，态度是不端正的。一来注释能让别人看懂并上手，易交接工作；二来过一段时间你修改BUG的时候，能很快捋清脉络。

1 注释模板

1.1 规约介绍

无规矩不成方圆，在讲注释模板前，我们先讲规范。要说规范哪家强？当然是阿里巴巴出的Java规约了。

alibaba/p3c：该开源项目有什么？

1.阿里巴巴Java开发手册.pdf,该pdf是大纲性的东西，没有经验的新手估计看不懂。

2.《码出高效》,这本书针对pdf列出了例子来讲解问题。

3.IDE plugin,看了上面两本书还怕犯错？没关系，还有IDE插件(针对IDEA和Eclipse)能帮你编码的时候检查是否符合规约。

1.2 注释约定

在阿里巴巴的规约中，有如下规定：

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

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

• 【说明】在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；在 IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

• ................

当然还有很多说明，此处就概括说明一下：

IDEA注释快捷键

单行注释(// 内容)：Ctrl + /
块注释(/* 内容 */)：Ctrl + Shift + /
说明注释(/** 内容 */)：/** + Enter (通常在方法名上方敲击。也可自己做成模板)

1.方法内部只能使用单行注释与块注释

2.除却方法内部注释外，其余所有注释均使用说明注释

3.所有注释都必须位于代码上方

PS：关于什么是Javadoc规范或者Javadoc注释标签，请自行百度。

1.3 IDEA注释模板

1.3.1 类注释模板

类注释

请按箭头顺序去理解。

• Reformat according to style，是否格式化注释。如果格式化，有可能会打乱@xxx的顺序。

可以看到，只要在模板上加上这么一段即可：

/**
 * ${description}
 * @author ${USER}
 * @create ${DATE} ${TIME}
 */

在新建类的时候就会自动生成注释了。

需要说明的是：

• .如果你的${xxx} 不存在于模板右下角的Description列表里，新建类时会自动弹出一个框，让你补上所有的${xxx}信息。

• .比如该模板中我增加了一个不存在于列表的 ${description}，当我新建类时：
  

  填写占位符的信息

新建类

1.3.2 方法注释模板

由于方法参数的不确定性，这里使用一点技巧来自动生成Javadoc规范的参数。

1.创建自己的Template Group：

MyGroup

2.创建第一个Live Template：

one_live.png

• Template Text如下：

第一个星号前面是没有空格的，余下的星号前面都有一个空格存在。这里最容易出错。

*
 * [方法描述]
$param$
 * @return $return$
 * @author $user$
 * @create $date$ $time$
 */

• 为该Live Template设置参数值。点击 Edit variables,设置自定义的 $xxx$参数：

one_live_values.png

这里的param不必选择Expresstion表达式，只需要填写Default value即可：

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

3.创建第二个Live Template：

two_live.png

其中 Change最开始为Define，只有选定了Live Template的范围才会变成Change。一般圈定范围为Java。而Options 的 Exand with 则根据个人习惯了。这里我两个都选择Enter。

Live Template 是如何生效的？

• 设定的 abbreviation(缩写的意思) + 设定的 Expand with
• 该模板【使用方法】：在方法名的上方敲，mc + 连续两次 Enter

mc.gif

至此，方法模板就结束了，关于模板的缩写设置，看个人习惯更改。

1.3.2 显示Javadoc注释

Ctrl + q :查看Javadoc文档
这里我准备一个遵守注释规约的Java文件：

package com.pcp.demo;
/**
 * 我是类描述：成员变量与方法模板演示
 * @author chaopeng
 * @create 2019/7/13 21:57
 */
public class JavaTemplate {

    /** 我是成员变量1的注释 */
    public double field1 = 1;
    /** 成员变量2 */
    public double field2 = 2;
    /** 成员变量3 */
    public double field3 = 3;

    /**
     * 我是方法描述：方法演示
     * @param param1 我是参数1描述 参数超链接{@link JavaTemplate#field1}
     * @param param2 我是参数2描述
     * @param param3 我是参数3描述
     * @return void 无返回值
     * @author chaopeng
     * @create 2019/7/14 17:29
     */
    public void m1(double param1,int param2,String param3) {

    }
}

在这个JavaTemplate.java文件中，符合Javadoc标签的有：

@param，表示参数
@return，表示返回值
{@link xxx}，表示可以跳转的超链接
当我们调用方法时，按一下 Ctrl + q，就能看到之前写的注释了

Javadoc.gif

2 编码技巧

类的编写，无非是类成员、类方法以及局部变量。

我们平时是如何写成员变量和方法的？无非就是按顺序写。

field_write.gif

2.1 编写成员变量的6种模板

• 实际只是省略public或private或= 或;
• 空格变成了Enter，写代码只需一路Enter
• 在自己的Template Group里新建6个Live Template
• 可自定义Live Template的$xxx$占位符名称

1.私有成员变量,不初始化，缩写：f.prif

private $field_type$ $field_name$;

2.私有成员变量,需初始化，缩写：f.prit

private $field_type$ $field_name$ = $field_value$;

3.公有成员变量,不初始化，缩写：f.pubf

public $field_type$ $field_name$;

4.公有成员变量,需初始化，缩写：f.pubt

public $field_type$ $field_name$ = $field_value$;

5.局部变量，不初始化，缩写：vf

$method_var_type$ $method_var$;

6.局部变量，需初始化，缩写：vt

$method_var_type$ $method_var$ = $var_value$;

一路Enter，不使用空格(看个人习惯)：

field.gif

2.2 编写方法的4种模板

• 实际只是省略public或private或() 或{}或;或void
• 空格变成了Enter，写代码只需一路Enter
• 在自己的Template Group里新建4个Live Template
• 可自定义Live Template的$xxx$占位符名称

1.私有方法，有返回值，缩写：m.pri.unvoid

private $method_type$ $method_name$($method_params$) {
    $method_content$
    return $method_return$;
}

2.私有方法，无返回值，缩写：m.pri.void

private void $method_name$($method_params$) {
    $method_content$
}

3.公有方法，有返回值，缩写：m.pub.unvoid

public $method_type$ $method_name$($method_params$) {
    $method_content$
    return $method_return$;
}

4.公有方法，无返回值，缩写：m.pub.void

public void $method_name$($method_params$) {
    $method_content$
}

一路Enter，写多个参数时要使用空格：

method.gif

这里就不讲Eclipse的模板设置了，事实上它内部已经集成了各种设置，只需要在对应的位置按下：Alt + Shift + j就会自动出现相应的注释了，百度有很多教程。

最后，稍微提下小技巧：

• 写完变量想新开下一行？

Shift + Enter

• 写完变量想新开上一行？

Ctrl + Altt + Enter

• 方法内部写完了想添加方法注释？

• Ctrl + {，跳到方法体的 {
• Ctrl + Alt + Enter，在方法名上方新开一行
• mc + 连续两次Enter，添加注释

• 方法注释写完了想继续添加方法？

• Ctrl + }，跳到类的}
• Ctrl + Alt + Enter，在类的}上方新开一行
• 编写方法

• 方法内部写完了想跳出方法体？

• Ctrl + }，跳到方法体的}
• Shift + Enter

• 最后别忘了格式化代码：

• Ctrl + Alt + L

PS:多记IDEA快捷键就对了。