代码规范 : 关于注释和日志

对于注释的要求

第一: 能够准确反应设计思想和代码逻辑
第二: 能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。
第三: 能自解释的代码就不要用注释

---

[javadoc]

幸运的是,java里有强大的javadoc 注释工具

类、类属性、类方法的注释使用 Javadoc 规范，
使用/*内容/格式，不得使用//xxx 方式

所有的抽象方法（包括接口中的方法） 必须要用 Javadoc 注释.
除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

以下是常见的javadoc 注释

    /** 
     * show 方法的作用简述. 
     * ＜p＞show 方法的详细说明第一行＜br＞ * show 方法的详细说明第二行
     * @author 作者 (类)
     * @version 版本号(类)
     * @see 对类、属性、方法的说明  参考转向，也就是相关主题  
     * @param 参数名 参数描述 
     * @return 返回的内容 
     * @throws 异常类名
     * @Exception 
     */

• 方法内部单行注释，使用//注释。
• 方法内部多行注释使用/* */注释，注意与代码对齐。
• 所有的枚举类型字段必须要有注释，说明每个数据项的用途。
• 注释的描述,尽可能的简单,有力 专有名词与关键字保持英文原文即可
• 特殊注释标记: TODO(还没实现的功能) （标记人，标记时间， [预计处理时间]); FIXME(不能工作) （标记人，标记时间， [预计处理时间])

注释的表述

• 注释代码段式应该注重’为何作’(why),而不是’怎么做’(How)
  不准确 : /* 进行io读写操作 */
  准确: /* 通过io读写 得到XXX文件里的数据 */

• 使用专业术语

  不准确 : /* 获取网络连接的状态 */
  准确 : /* TCP 连接状态 */

• 注释数据声明:

  1. 注释数值的单位
  2. 对数值的允许范围给出注释
  3. 注释编码含义
  4. 注释对输入数据的限制
  5. 注释’位标志’
  6. 注释全局数据
  7. 将于变量有关的注释通过变量名关联起来

• 注释控制结构:

  1 应该在每一个if,循环,或者代码段前面加注释
  2 应在每个冗长的控制结构之后加上注释
  3 区分输入和输出的数据,用 in 或者 out 注释
  4 对子程序的局限性,碰到麻烦的行为,就要注释

---

日志

• 用stf4j api, 不要使用应用中日志系统（Log4j、 Logback） 中的 API，
• 日志文件推荐至少保存 15 天
• 对 trace/debug/info 级别的日志输出，必须使用条件输出形式或者使用占位符的方式
• 可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适从。
• 生产环境禁止输出 debug 日志； 有选择地输出 info 日志；