java注释

注释的意义

      注释即文档，当别人阅读自己的代码或者自己review自己的代码时，注释对于帮助理解代码起到重要作用。

注释的风格

1. 行注释
   //comment on one line
2. 块注释
   /* comment on one
   or more line */
3. 文档注释
   /* documenting comment /

注释的规范

      注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。可以用注释统计工具来统计。

• 一般情况下，源程序有效注释量必须在30％以上。
• 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。
• 注释的内容要清楚、明了，含义准确，防止注释二义性。
• 包的注释内容：简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。
• 类和接口的注释：该注释放在 package 关键字之后，class 或者 interface 关键字之前。类的注释主要是一句话功能简述、功能详细描述。
• 类属性、公有和保护方法注释：写在类属性、公有和保护方法上面。
• 成员变量注释内容：成员变量的意义、目的、功能，可能被用到的地方。
• 公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
• 对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
• 等等

注释的格式

• 类和接口注释格式：

/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
 * @author     [作者]
 * @version   [版本号, YYYY-MM-DD]
 * @param [参数1]     [参数1说明]
 * @param [参数2]     [参数2说明]
 * @return  [返回类型说明]
 * @exception/throws [违例类型] [违例说明]
 * @see          [类、类#方法、类#成员]
 * @deprecated
 */
 说明：描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，@since 表示从那个版本开始就有这个类或者接口，@deprecated 表示不建议使用该类或者接口。

• 公有和保护方法注释格式：

/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
 * @param [参数1]     [参数1说明]
 * @param [参数2]     [参数2说明]
 * @return  [返回类型说明]
 * @exception/throws [违例类型] [违例说明]
 * @see          [类、类#方法、类#成员]
 * @deprecated
 */
说明：@since 表示从那个版本开始就有这个方法；@exception或throws 列出可能仍出的异常；@deprecated 表示不建议使用该方法。

• 对属性进行单行注释等

        Java注释对帮助理解代码有很重要的作用，公司团队应该遵循一套标准统一的Java注释规范，便于开发和团队协作。