java注释规范

最新推荐文章于 2021-03-19 23:15:52 发布

weixin_30929011

最新推荐文章于 2021-03-19 23:15:52 发布

阅读量274

点赞数

文章标签： java

原文链接：http://www.cnblogs.com/liusxg/p/5277068.html

版权

前言：

现在java的出产地sun公司并没有定义一个java注释规范，注释规范目前是每个公司自己有自己的一套规范，主要是为了团队之间的协作。

1、基本规则

1.注释应该使代码更加清晰易懂

2.注释要简洁明了，只要提供能够明确理解程序必要的信息就可以了。如果注释太复杂会影响程序整洁度和阅读感。

3.注释不仅描述程序作了什么，还要描述为什么这样做以及约束。

4.对于一般的getter和setter方法不用注释。

5.类、接口、构造函数、方法、全局变量必须添加注释。字段属性可以选择添加简单注释。

6.简单注释一般不超过10个字。

7.特殊地方必须要添加注释。比如一下几个地方：典型算法，代码不明晰处，在代码修改处，在循环和逻辑分支组成代码处，为他人提供的接口。

2、三种注释方式

1.单行注释（single-line）：//注释内容

一次只能注释一行，一般是简单注释，用来简短描述某个变量或属性，程序块。

2.块注释（block）：/*注释内容*/

为了进行多行简单注释，一般不使用。

3.文档注释：/**注释内容 */

可以使用多行，一般用来对类、接口、成员方法、成员变量、静态字段、静态方法、常量进行说明。Javadoc可以用它来产生代码的文档。为了可读性，可以有缩进和格式控制。

文档注释常采用一些Javadoc标签进行文档的特定用途描述，用于帮助Javadoc产生文档，常用的有：

标签	用途	说明
@author name	类/接口	描述代码的作者，每个作者对应一个标签。
@Description	类/接口/方法	对类，方法，接口的简单描述
@deprecated	类/成员方法	说明该API已经废除。
@exception name description 或 @throws name description	成员方法	描述方法抛出的异常，每一个异常对应一个标签
@param name description	成员方法	描述成员方法中参数用途和意义，一个参数对应一个标签
@return description	成员方法	描述成员方法的返回值的意义
@since	类/接口/成员方法	描述该API最初出现时间，可以填写版本号
@see ClassName	类/接口/成员方法/成员变量	用于引用特定的类的成员方法的描述，参考转向，一般ClassName是包括包名的全名
@data	类/接口/方法	用于显示类，方法，接口具体创建时间，或者修改时间
@version text	类/接口	版本
@inheritDoc	类/接口/成员方法	继承的文档
{@link address} 或者 @ linkplain address text}	类/接口/方法	用于创建一个指向另一份文档的超链接