java注释规范


1. 类和接口的注释

类和接口必须写注释。注释放在package关键字后,class前。

package com.xxx.xx.xxx.xx;
/**
 * 注释内容
 */
public class xxx
  • 类和接口的注释内容主要是一句话的简述功能,功能详细描述。
/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
*/

2.成员变量的注释

注释内容:成员变量的意义、目的、功能,写在类属性的上面。

/**
 * 注释内容
 */
private String xxx;

3.类方法的注释

注释内容:列出方法的功能简述、功能详细描述,输入参数、输出参数、返回值、异常处理等。

/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
 * @param  [参数1] [in或out]  [参数1说明]
 * @param  [参数2] [in或out]  [参数2说明]
 * @return [返回类型说明]
 * @exception/throws [违例类型] [违例说明]
*/
/**
 * 用MD5算法计算输入字符串的32位摘要
 * @param sIn [in] 待处理的字符串
 * @param sOut [out] sIn的32为摘要,调用函数负责new sOut对象
 * @return boolean
 */
public static boolean getMd5(String sIn, StringBuffer sOut) 

注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。

注释与所描述内容进行同样的缩排。
说明:可使程序排版整齐,并方便注释的阅读与理解。

//注释
program code one
(空一格)   
//注释
program code two

javadoc使用方式

标签 说明
@author 作者标识
@version 版本号
@return 对函数返回值的描述
@deprecated 标识过期API
@throws 构造函数或方法会抛出的异常
@exception 同@throws
@see 引用
@link 引用
@value 对常量注释
@code 将文本标记为code
@param 说明方法中的参数
@inheritDoc 用于继承父类的JavaDoc

文章作者: rainbow
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 rainbow !
  目录