java注释

注释的意义

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

注释的风格

行注释

//comment on one line

块注释

/* comment on one

or more line */

文档注释

/* 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注释规范，便于开发和团队协作。