JAVA 注释格式

1. 文件注释: (文件注释写入文件头部，包名之前的位置)

说明: 注意以 /* 开始 避免补JavaDoc收集

/*
 * 注释内容
 */
package com.fsdn.msg;

2. 文件注释内容: 版权说明、描述信息、生成日期、修改历史

说明: 文件名可选

/*
 * 文件名: [文件名]
 * 版权: <版权>
 * 描述: <描述>
 * 修改人: <修改人>
 * 修改时间: YYYY-MM-DD
 * 修改单号: <修改单号>
 * 修改内容: <修改内容>
 * /

说明: 每次修改后在文件头部写明修改信息,CheckIn的时候可以直接把蓝色字体信息粘贴到VSS的注释上。在代码受控之前可以免去。

示例:

/*
 * 文件名: LogManager.java
 * 版权: Copyright 2002-2007 Huawei Tech. Co. Ltd. All Rights Reserved.
 * 描述: MMSC V100R002 Relay 通用日志系统
 * 修改人: 张三
 * 修改时间: 2017-02-01
 * 修改内容: 新增
 * 修改人: 李四
 * 修改时间: 2017-02-10
 * 修改单号: WSS368
 * 修改内容: xxx
 * /

3. 类和接口的注释: 该注释放在package关键字之后,class或者interface关键字之前。

说明: 方便JavaDoc收集

package com.fsdn.msg;

/**
 * <一句话功能简述>
 * <功能详细描述>
 * @author  [作者]
 * @version [版本号, YYYY-MM-DD]
 * @see     [相关类/方法]
 * @since   [产品/模块版本]
 * @deprecated
 */
public class LogManager

示例:

package com.fsdn.msg;

/**
 * LogManager 类集中控制对日志读写的操作
 * 全部为静态变量和静态方法,对外提供统一接口。
 * 分配对应日志类型的读写器,读取或写入符合条件的日志纪录。
 * @author  张三,李四,王五
 * @version 1.2， 2017-02-01
 * @see     LogIteraotor
 * @since   CommonLog 1.0
 */
public class LogManager

4. 类属性、公有和保护方法注释: 写在类属性、仅有和保护方法上面。

格式:

/**
 * <一句话功能简述>
 * <功能详细描述>
 * @param  [参数1] [参数1说明]
 * @param  [参数2] [参数2说明]
 * @return [返回类型说明]
 * @exception/throws [违例类型] [违例说明]
 * @see    [类、类#方法、类#成员]
 * @deprecated
 */

示例：

/**
 * 根据日志类型和时间读取日志
 * 分配对应日志类型的LogReader, 指定类型、查询时间段、条件和反复器缓冲数，读取日志记录。
 * 查询条件为null或0表示无限制,反复器缓冲数为0读不到日志查询时间为左包含原则,即 [startTime, endTime]
 * @param  logTypeName 日志类型名 (在配置文件中定义的)
 * @param startTime 查询日志的开始时间
 * @param endTime   查询日志的结束时间
 * @param logLevel  查询日志的级别
 * @param userName  查询该用户的日志
 * @param bufferNum 日志反复器缓冲记录数
 * @return 结果集, 日志反复器
 * @see    CommonLog 1.0
 */
public static LogIterator read(String logType, Date startTime, Date endTime, int logLevel, String userName, int bufferNum)

说明: 对于方法内部用throw语句抛出的异常, 必须在方法的注释中标明, 对于所调用的其他方法所抛出的异常，选择主要的在注释中说明。对于非RuntimeException,即throws子句声明会抛出的异常，必须在方法的注释中标明。

注意:

// 推荐使用
@exception  // 标注 Runtime 异常

@throws     // 标注非 Runtime 异常, 异常的注释必须说明该导演的含义及什么条件下抛出该异常