java注释规范
Posted 破阵
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了java注释规范相关的知识，希望对你有一定的参考价值。
前言：
现在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} | 类/接口/方法 | 用于创建一个指向另一份文档的超链接 |
3、实例
1.文件注释
一般作比较详细描述，而且在同个项目里面统一使用，主要包括：版权声明，license许可证描述。
示例（来自 spring-framework）：
/*
* Copyright 2002-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
2.类/接口注释
类，接口描述，一般作详细描述。按照常用的说明顺序呢排列，主要包括
1.类的描述，以。或.结束。
2.类设计的目标，完成什么样的功能一般和类的描述合并在一起。
3.<Strong>主要的类使用</Strong>如何使用该类，包括环境要求，比如线程是否安全，并发性要求以及使用约束。
4.<Strong>已知的BUG</Strong>
5.描述类的修改历史：<Strong>修改人+日期+简单说明</Strong>
[email protected]作者、@version版本，@see参照，@since开始版本信息
示例（来自spring-framework）：
/**
* Delegate for resolving constructors and factory methods.
* Performs constructor resolution through argument matching.
*
* @author Juergen Hoeller
* @author Rob Harrop
* @author Mark Fisher
* @author Costin Leau
* @since 2.0
* @see #autowireConstructor
* @see #instantiateUsingFactoryMethod
* @see AbstractAutowireCapableBeanFactory
*/
3.方法注释
方法描述说明，主要对方法的描述，参数、返回值、抛出异常进行说明。
示例（来自spring-framework）
/**
* Resolve the factory method in the specified bean definition, if possible.
* {@link RootBeanDefinition#getResolvedFactoryMethod()} can be checked for the result.
* @param mbd the bean definition to check
* @return a BeanWrapper for the new instance
* @throws Exception in case of any kind of processing failure
*/
4.修改注释
在修改处一定要添加注释，说明修改人，修改原因，修改内容，修改时间
以上是关于java注释规范的主要内容，如果未能解决你的问题，请参考以下文章