美文网首页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