2.1 规则

规则1 类和接口的注释放在class或者interface关键字之前，import关键字之后。注释主要是一句话功能简述与功能详细描述。类注释使用"/**...*/"注释方式

说明：方便JavaDoc收集，没有import可放在package之后。注释可根据需要列出：作者、内容、功能、与其他类的关系等。功能详细描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，@since表示从那个版本开始就有这个类或者接口，@deprecated表示不建议使用该类或接口。

/**
 * <一句话功能简述>
 * <功能详细描述>
 * @author      [作者]（必须）
 * @see         [相关类/方法]（可选）
 * @since       [产品/模块版本]（必须）
 * @Copyright   [产品版权]（必须）
 * @deprecated  （可选）
 */

示例：

package com.dg11185.framework.util;

import java.util.*;

/**
 * <一句话功能简述>
 * <功能详细描述>
 * @author      [作者]（必须）
 * @see         [相关类/方法]（可选）
 * @since       [产品/模块版本]（必须）
 * @Copyright   [产品版权]（必须）
 * @deprecated  （可选）
 */
public class LogManager {
    ...
}

规则2 类属性（成员变量）、公有和保护方法注释：写在类属性、公有和保护方法上面，注释方式为"/**...*/"。

示例：

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

/**
 * 注释内容
 */
public void write() {
    ...
}

规则3 公有和保护方法注释内容：列出方法的一句话功能简介、功能详细描述、输入参数、输出参数、返回值、异常等。

格式：

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

说明：@since 表示从那个版本开始就有这个方法，如果是最初版本就存在的方法无需说明；@exception或throws 列出可能抛出的异常；@deprecated 表示不建议使用该方法。

示例：

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

规则4 方法的入参中如果包含集合类，或者返回结果是集合类。例如map、list、set以及其他集合类时，必须指明集合中元素的类型和含义。Map类型必须对key和value都加以说明。

示例：

/**
 * 获取待练习题库中的所有考题，并进行随机排序，排序方式为根据考题ID大小
 * 
 * @param sid   日志类型名（在配置文件中定义的）
 * @param count 查询日志的开始时间
 * 
 * @return map 存储当前需要练习的考题顺序号和考题ID，
 * 其结构为：键 == 考题顺序号
 *         值 == 考题ID
 */
public HashMap<String, String> getRandomByQuestionId(String sid, int count, int type) throws Exception {
    ...
}

规则5 在其他人编写的类中添加方法时，必须注明方法的作者和日期。其它注释参照方法的常规注释。

规则6 修改他人方法时，必须注明修改人、修改日期、修改理由，描述（可能带来的）影响。

规则7 对于switch语句下的case语句，必须在每个case分支结束前加上break语句。

说明：break才能真正表示该switch执行结束，不然可能会进入该case以后的分支，至于语法上合法的场景“一个case后进入下一个case处理”，应该在编码设计上就避免。

规则8 修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

规则9 注释的内容要清楚、明了，含义准确，防止注释二义性。

说明：错误的注释不但无益反而有害

规则10 避免在注释中使用缩写，特别是不常用缩写。

说明：在使用缩写时或之前，应对缩写进行必要的说明。

规则11 对重载父类的方法必须进行@Override声明。