全部博文（2065）
分类： Java
2008-11-11 14:55:24
Java注释规范整理[范本]
整理人：遥方 整理时间：
说明：将来全部的代码里面的注释统一使用里面的注释规则。
一、源文件注释[即一篇源文件头部的注释信息]
源文件注释采用 /** …… */，在每个源文件的头部要有必要的注释信息。
包括：文件名；文件编号；版本号；作者；创建时间；文件描述包括本文件历史修改记录等。
中文注释模版：
/**
* 文 件 名 :
* CopyRright (c) 2008-xxxx:
* 文件编号：
* 创 建 人：
* 日
期：
* 修 改 人：
* 日
期：
* 描
述：
* 版 本 号：
*/
一篇源码文件的注释格式如下所示
二、类或模块的注释
类（模块）注释采用 /** …… */，在每个类（模块）的头部要有必要的注释信息。
包括：工程名；类（模块）编号；命名空间；类可以运行的JDK版本；版本号；作者；创建时间；类（模 块）功能描述（如功能、主要算法、内部各部分之间的关系、该类与其类的关系等，必要时还要有一些如特别的软硬件要求等说明）；主要函数或过程清单及本类 （模块）历史修改记录等。
英文注释模版：
/**
* CopyRright (c)2008-xxxx: <展望软件Forsoft
>
*Project: <项目工程名>
*Module ID: <(模块)类编号，可以引用系统设计中的类编号>
*Comments: <对此类的描述，可以引用系统设计中的描述>
* JDK version used:
* Namespace: <
* Author：
<作者中文名或拼音缩写>
* Create Date： <创建日期，格式:YYYY-MM-DD>
*Modified By：
<修改人中文名或拼音缩写>
*Modified Date: <修改日期，格式:YYYY-MM-DD>
* Why & What is modified <修改原因描述>
*
Version:
<版本号>
*/
如果模块只进行部分少量代码的修改时，则每次修改须添加以下注释：
//Rewriter
//Rewrite Date：<修改日期:格式YYYY-MM-DD>
Start1：
/* 原代码内容*/
三、接口注释
接口注释采用 /** …… */，在满足类注释的基础之上，接口注释应该包含描述接口的目的、它应如何被使用以及如何不被使用，块标记部分必须注明作者和版本。在接口注释清楚的前提 下对应的实现类可以不加注释。
接口 = 类+ 接口的目的 + 如何使用
四、构造函数
构造函数注释采用 /** …… */，描述部分注明构造函数的作用，不一定有块标记部分。
注释模版一：
/**
* 默认构造函数
*/
注释模版二：
/**
* Description : 带参数构造函数,
*
初始化模式名,名称和数据源类型
* @param schema：
模式名
* @param name：
名称
* @param type： 数据源类型
*/
五、函数方法
函数注释采用 /** ……*/，在每个函数或者过程的前面要有必要的注释信息，
包括：函数或过程名称；功能描述；输入、输出及返回值说明；调用关系及被调用关系说明等。函数注 释里面可以不出现版本号（@version）。
注释模版一：
/**
* 函 数 名 :
* 功能描述：
* 输入参数:
<按照参数定义顺序>
*
<@param后面空格后跟着参数的变量名字
* （不是类型），空格后跟着对该参数的描述。>
*
* 返 回 值: - 类型 <说明>
* <返回为空（void）的构造函数或者函数，
* @return可以省略; 如果返回值就是输入参数，必须 * 用与输入参数的@param相同的描述信息; 必要的时*
候注明特殊条件写的返回值。>
* 异
常：<按照异常名字的字母顺序>
* 创 建 人:
* 日
期:
* 修 改 人:
* 日
期:
*/
注释模版二：
/**
* FunName:
getFirstSpell
* Description : 获取汉字拼音首字母的字符串，
*
被生成百家姓函数调用
* @param：
str the String是包含汉字的字符串
* @return String：汉字返回拼音首字母字符串；
*
英文字母返回对应的大写字母；
*
其他非简体汉字返回 '0'；
* @Author: ghc
* @Create Date:
*/
六、方法内部注释
控制结构，代码做了些什么以及为什么这样做，处理顺序等，特别是复杂的逻辑处理部分，要尽可能的给出详细的注释。（对某些方法的注释要非常明确）
七、全局变量注释
要有较详细的注释，包括对其功能、取值范围、哪些函数或者过程存取以及存取时注意事项等的说明。
JavaDoc的格式：
@author 对类的说明 标明开发该类模块的作者
@version 对类的说明 标明该类模块的版本
@see 对类、属性、方法的说明 参考转向，也就是相关主题
@param 对方法的说明 对方法中某参数的说明
@return 对方法的说明 对方法返回值的说明
@exception 对方法的说明 对方法可能抛出的异常进行说明
示范：
/**
* 文件名: StringsUtils.java
* CopyRright(c) 2010-03
* 创 建 人： hkebao@126.com
* 日 期：
* 描 述： 实现字符串操作工具类
* 版 本 号： V1.0
*/
/**
*CopyRright (c)2010-03: JAVA基础工具库
*Project:
*Module ID: <1.0>
*Comments: <定义JAVA字符串常用操作>
*JDK version used:
*Author：
*Create Date： <
*Version: <1.0>
*/
public class StringsUtils {
/**
* 默认构造函数
*/
public StringsUtils() {
}
/**
* FunName: getStringLength
* Description : 获取字符串长度
* @param： 字符串 str
* @return String： 字符串长度
* @Author: XXX
* @Create Date:
*/
public int getStringLength(String content) {
return content.length();
}
}
