美文网首页Java
代码注释及编码技巧(Java版)

代码注释及编码技巧(Java版)

作者: 呆鹏斩翅 | 来源:发表于2019-07-14 22:34 被阅读0次

工欲善其事,必先利其器!

个人以为,写代码不加注释,态度是不端正的。一来注释能让别人看懂并上手,易交接工作;二来过一段时间你修改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种模板

  • 实际只是省略publicprivate=;
  • 空格变成了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种模板

  • 实际只是省略publicprivate(){};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快捷键就对了。

相关文章

网友评论

    本文标题:代码注释及编码技巧(Java版)

    本文链接:https://www.haomeiwen.com/subject/ugdbkctx.html