工欲善其事,必先利其器!
个人以为,写代码不加注释,态度是不端正的。一来注释能让别人看懂并上手,易交接工作;二来过一段时间你修改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:
MyGroup2.创建第一个Live Template:
one_live.png- Template Text如下:
第一个星号
前面是没有空格的,余下的星号
前面都有一个空格存在。这里最容易出错。
*
* [方法描述]
$param$
* @return $return$
* @author $user$
* @create $date$ $time$
*/
- 为该Live Template设置参数值。点击 Edit variables,设置自定义的
$xxx$
参数:
这里的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
至此,方法模板就结束了,关于模板的缩写设置,看个人习惯更改。
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) {
}
}
Javadoc.gif在这个JavaTemplate.java文件中,符合Javadoc标签的有:
@param,表示参数
@return,表示返回值
{@link xxx},表示可以跳转的超链接
当我们调用方法时,按一下Ctrl + q
,就能看到之前写的注释了
2 编码技巧
类的编写,无非是类成员、类方法以及局部变量。
我们平时是如何写成员变量和方法的?无非就是按顺序写。
field_write.gif2.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,不使用空格(看个人习惯):
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快捷键就对了。
网友评论