【代码规范】常见注释规范

文章来源：公众号-智能化IT系统。

1.在有处理逻辑的代码中，源程序有效注释量必须在20％以上。

说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。

 

2.文件注释：文件注释写入文件头部。

说明：以/* 开始

示例：

/ * * 文件名：[文件名] * 作者：〈版权〉 * 描述：〈描述〉 * 修改人：〈修改人〉 * 修改时间：YYYY-MM-DD  * 修改内容：〈修改内容〉   */

 

说明：每次修改后在文件头部写明修改信息。

示例：

/ * * 文件名：LogManager.java * 版权：Copyright 2000-2001 Huawei Tech. Co. Ltd.  All Rights Reserved. * 描述： WIN V200R002 WEBSMAP 通用日志系统 * 修改人：张三 * 修改时间：2001-02-16 * 修改内容：新增 * 修改人：李四 * 修改时间：2001-02-26 * 修改内容：。。。。。。 * 修改人：王五 * 修改时间：2001-03-25 * 修改内容：。。。。。。  */

 

3.类和接口的注释：该注释放在class定义之前，using或package关键字之后。

示例：

package com. websmap.comm; /**  * 注释内容  */  public class CommManager

 

4.类和接口的注释内容：类的注释主要是一句话功能简述、功能详细描述，说明：可根据需要列出：版本号、生成日期、作者、内容、功能、与其它类的关系等。

格式：

/ *  * 〈一句话功能简述〉 * 〈功能详细描述〉 * @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 */

5.类属性、公有和保护方法注释：写在类属性、公有和保护方法上面。用//来注释,需要对齐被注释代码。

示例：

/ /注释内容 private  String logType

 

6.成员变量注释内容：成员变量的意义、目的、功能，可能被用到的地方。用//来注释,需要对齐被注释代码

7.公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
格式：

/ ** *〈一句话功能简述〉 *〈功能详细描述〉 * @param [参数1] [参数1说明] * @param [参数2] [参数2说明] * @return [返回类型说明] * @exception/throws [违例类型] [违例说明] * @see [类、类#方法、类#成员]  * @deprecated */

说明：@since 表示从那个版本开始就有这个方法；@exception或throws 列出可能出现的异常；@deprecated 表示不建议使用该方法。

 

8.对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出的异常，选择主要的在注释中说明。对于非RuntimeException ，即throws子句声明会抛出的异常，必须在方法的注释中标明。

说明：

异常注释用@exception或@throws表示，在JavaDoc中两者等价，但推荐用@exception标注Runtime 异常，@throws标注非Runtime 异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。

 

9.注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。

 

10.注释的排版，按照上述示例来展示。

11.注释应该放在被注释的代码前面，分行展示，但中间不留空行。

12.对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：分支语句往往是程序实现某一特定功能的关键。

 

13.边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

 

14.注释的内容要清楚、明了，含义准确，防止注释二义性。说明：错误的注释不但无益反而有害。

 

15.避免在注释中使用缩写，特别是不常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。

---

公众号-智能化IT系统。每周都有技术文章推送，包括原创技术干货，以及技术工作的心得分享。扫描下方关注。