mirror of
https://gitee.com/tawords/tawords-docs
synced 2025-01-11 20:08:16 +08:00
4.8 KiB
4.8 KiB
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.对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
说明：分支语句往往是程序实现某一特定功能的关键。