代码一方面是要给计算机读懂去执行的,一方面是要让人能更好的理解和维护。为了更好的理解和维护,所以需要使用注释来辅助理解。

毕竟没有人希望读个代码像跑马拉松一样疲劳吧,我见过成百上千行代码注释不超过十行的,真的是一场灾难。

有人可能会说我自己写的代码,就我一个人维护,不用写注释,浪费时间,但是我要说,短期可能还可以,但是过一个月以后再想修改自己的代码,就跟改别人的差不多了。

真的,有我自己的亲身体验,也有很多同事不止一次的抱怨过看不懂以前写的代码。

下面简单的介绍一下注释,注释有三种:

单行注释//

可以单独一行,也可以在代码末尾,//后面的内容不会被程序执行。

多行注释/*    */

可以注释单行,也可以注释多行,/*开头*/结尾中间的内容不会被程序执行。

文档注释/**   */

这种注释可以用来自动地生成文档。在JDK中有个javadoc的工具,可以由源文件生成一个HTML文档。

文档注释位置
(1)类注释。类注释用于说明整个类的功能、特性等,它应该放在所有的“import”语句之后,在class定义之前。这个规则也适用于接口(interface)注释。    

(2)方法注释。方法注释用来说明方法的定义,比如,方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。    

(3)属性注释。默认情况下,javadoc只对公有(public)属性和受保护属性(protected)产生文档——通常是静态常量。    

推荐两个文档注释的模板:

类注释

/**
 * @class_name: AAServiceImpl
 * @package: com.aa.service.aa.impl
 * @Description: AA实现类
 * @creat_user: name
 * @creat_date: 2018/11/15
 * @creat_time: 18:57
 **/

方法注释

/**
 * @method: convertList
 * @Description:  
 * @Param: [list] 
 * @return: java.util.List<com.aa.model.aa.AADetail>  
 * @creat_user: name
 * @creat_date: 2018/11/15
 * @creat_time: 18:59
 * @modify1: by name on 2018/11/15
 **/

 

最后修改于 2018-11-15 18:52:55
如果觉得我的文章对你有用,请随意赞赏
扫一扫支付
上一篇