Java 注释规范及快捷键
1.1.0快捷键
a.调出你自己写好的默认注释： /** + 回车
b.// ：ctrl + /
c.多行注释 ：选中多行,ctrl+/
1.1.1. 一般情况下，源程序有效注释量必须在30％以上。
说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。可以用注释统计工具来统计。
1.1.2. 包的注释：包的注释写入一名为 package.html 的HTML格式说明文件放入当前路径。
说明：方便JavaDoc收集
示例：
com/huawei/msg/relay/comm/package.html
1.1.3. 包的注释内容：简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。
说明：在详细描述中应该说明这个包的作用以及在整个项目中的位置。
格式：
一句话简述。
详细描述。
产品模块名称和版本
公司版权信息
示例：
为 Relay 提供通信类，上层业务使用本包的通信类与SP进行通信。
详细描述。。。。。。。。
MMSC V100R002 Relay
(C) 版权所有 2002-2007 文思创新技术有限公司
1.1.4. 文件注释：文件注释写入文件头部，包名之前的位置。
说明：注意以 /* 开始避免被 JavaDoc 收集
示例：
/*
* 注释内容
*/
package com.huawei.msg.relay.comm;
1.1.5. 文件注释内容：版权说明、描述信息、生成日期、修改历史。
说明：文件名可选。
格式：
/*
* 文件名：[文件名]
* 版权：〈版权〉
* 描述：〈描述〉
* 修改人：〈修改人〉
* 修改时间：YYYY-MM-DD
* 修改单号：〈修改单号〉
* 修改内容：〈修改内容〉
*/
说明：每次修改后在文件头部写明修改信息，CheckIn的时候可以直接把蓝色字体信息粘贴到VSS的注释上。在代码受控之前可以免去。
示例：
/*
* 文件名：LogManager.java
* 版权：Copyright 2002-2007 Huawei Tech. Co.Ltd. All Rights Reserved.
* 描述： MMSC V100R002 Relay通用日志系统
* 修改人： 张三
* 修改时间：2001-02-16
* 修改内容：新增
* 修改人：李四
* 修改时间：2001-02-26
* 修改单号：WSS368
* 修改内容：。。。。。。
* 修改人： 王五
* 修改时间：2001-03-25
* 修改单号：WSS498
* 修改内容：。。。。。。
*/
1.1.6. 类和接口的注释：该注释放在 package 关键字之后，class 或者 interface 关键字之前。
说明：方便JavaDoc收集。
示例：
package com.huawei.msg.relay.comm;
/**
* 注释内容
*/
public class CommManager
1.1.7. 类和接口的注释内容：类的注释主要是一句话功能简述、功能详细描述。
说明：可根据需要列出：版本号、生成日期、作者、内容、功能、与其它类的关系等。 如果一个类存在Bug，请如实说明这些Bug。
格式：
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @author [作者]
* @version [版本号, YYYY-MM-DD]
* @see [相关类/方法]
* @since [产品/模块版本]
* @deprecated
*/
说明：描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，@since 表示从那个版本开始就有这个类或者接口，@deprecated 表示不建议使用该类或者接口。
示例：
/**
* LogManager 类集中控制对日志读写的操作。
* 全部为静态变量和静态方法，对外提供统一接口。分配对应日志类型的读写器，
* 读取或写入符合条件的日志纪录。
* @author 张三，李四，王五
* @version 1.2, 2001-03-25
* @see LogIteraotor
* @see BasicLog
* @since CommonLog1.0
*/
1.1.8. 类属性、公有和保护方法注释：写在类属性、公有和保护方法上面。
示例：
/**
* 注释内容
*/
private String logType;
/**
* 注释内容
*/
public void write()
1.1.9. 成员变量注释内容：成员变量的意义、目的、功能，可能被用到的地方。
1.1.10. 公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
格式：
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @param [参数1] [参数1说明]
* @param [参数2] [参数2说明]
* @return [返回类型说明]
* @exception/throws [违例类型] [违例说明]
* @see [类、类#方法、类#成员]
* @deprecated
*/
说明：@since 表示从那个版本开始就有这个方法；@exception或throws 列出可能仍出的异常；@deprecated 表示不建议使用该方法。
示例：
/**
* 根据日志类型和时间读取日志。
* 分配对应日志类型的LogReader， 指定类型、查询时间段、条件和反复器缓冲数，
* 读取日志记录。查询条件为null或0表示无限制，反复器缓冲数为0读不到日志。
* 查询时间为左包含原则，即 [startTime, endTime) 。
* @paramlogTypeName 日志类型名（在配置文件中定义的）
* @paramstartTime 查询日志的开始时间
* @param endTime 查询日志的结束时间
* @param logLevel 查询日志的级别
* @param userName 查询该用户的日志
* @parambufferNum 日志反复器缓冲记录数
* @return 结果集，日志反复器
* @since CommonLog1.0
*/
publicstatic LogIterator read(String logType, Date startTime, Date endTime,
intlogLevel, String userName, int bufferNum)
1.1.11. 对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出的异常，选择主要的在注释中说明。对于非RuntimeException，即throws子句声明会抛出的异常，必须在方法的注释中标明。
说明：异常注释用@exception或@throws表示，在JavaDoc中两者等价，但推荐用@exception标注Runtime异常，@throws标注非Runtime异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。
1.1.12. *注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
1.1.13. *注释与所描述内容进行同样的缩排。
说明：可使程序排版整齐，并方便注释的阅读与理解。
示例：如下例子，排版不整齐，阅读稍感不方便。
public voidexample( )
{
// 注释
CodeBlockOne
// 注释
CodeBlockTwo
}
应改为如下布局。
public void example( )
{
// 注释
CodeBlock One
// 注释
CodeBlock Two
}
1.1.14. *将注释与其上面的代码用空行隔开。
示例：如下例子，显得代码过于紧凑。
//注释
program code one
//注释
program code two
应如下书写：
//注释
program code one
//注释
program code two
1.1.15. *对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。
1.1.16. *对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。
1.1.17. *边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。
1.1.18. *注释的内容要清楚、明了，含义准确，防止注释二义性。
说明：错误的注释不但无益反而有害。
1.1.19. *避免在注释中使用缩写，特别是不常用缩写。
说明：在使用缩写时或之前，应对缩写进行必要的说明。
1.2. 建议
1.2.1. *避免在一行代码或表达式的中间插入注释。
说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。
1.2.2. *通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
1.2.3. *在代码的功能、意图层次上进行注释，提供有用、额外的信息。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。
示例：如下注释意义不大。
// 如果 receiveFlag 为真
if (receiveFlag)
而如下的注释则给出了额外有用的信息。
// 如果从连结收到消息
if (receiveFlag)
1.2.4. *在程序块的结束行右方加注释标记，以表明某程序块的结束。
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。
示例：参见如下例子。
if (...)
{
program code1
while (index { program code2 } // end of while(index < MAX_INDEX) // 指明该条while语句结束 } // end of if (...)// 指明是哪条if语句结束 说明：注释语言不统一，影响程序易读性和外观排版，出于维护的考虑，建议使用中文。 说明：调试程序的时候可以方便的使用 /* 。。。*/ 注释掉一长段程序。 说明：JavaDoc工具收集简介的时候使用选取第一句话。 示例：如下是对设置属性的流程注释 //1、 判断输入参数是否有效。 。。。。。 // 2、设置本地变量。 。。。。。。 示例：这里主要是对闰年算法的说明。 //1. 如果能被4整除，是闰年； //2. 如果能被100整除，不是闰年.； //3. 如果能被400整除，是闰年.。1.2.5. *注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。
1.2.6. 方法内的单行注释使用 //。
1.2.7. 注释尽量使用中文注释和中文标点。方法和类描述的第一句话尽量使用简洁明了的话概括一下功能，然后加以句号。接下来的部分可以详细描述。
1.2.8. 顺序实现流程的说明使用1、2、3、4在每个实现步骤部分的代码前面进行注释。
1.2.9. 一些复杂的代码需要说明。