mirror of
https://gitee.com/tawords/tawords-docs
synced 2025-01-11 20:08:16 +08:00
118 lines
4.8 KiB
Markdown
118 lines
4.8 KiB
Markdown
#### 1.在有处理逻辑的代码中，源程序有效注释量必须在20％以上。
|
||
> 说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。
|
||
|
||
#### 2.文件注释：文件注释写入文件头部。
|
||
> 说明：以`/**`开始
|
||
|
||
示例：
|
||
```php
|
||
/**
|
||
* 文件名：[文件名]
|
||
* 作者：〈版权〉
|
||
* 描述：〈描述〉
|
||
* 修改人：〈修改人〉
|
||
* 修改时间：YYYY-MM-DD
|
||
* 修改内容：〈修改内容〉
|
||
*/
|
||
```
|
||
> 说明：每次修改后在文件头部写明修改信息。
|
||
|
||
示例：
|
||
```php
|
||
/**
|
||
* 文件名：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` 关键字之后。
|
||
示例：
|
||
```php
|
||
package com.websmap.comm;
|
||
|
||
/**
|
||
* 注释内容
|
||
*/
|
||
public class CommManager
|
||
```
|
||
#### 4.类和接口的注释内容：类的注释主要是一句话功能简述、功能详细描述，说明：可根据需要列出：版本号、生成日期、作者、内容、功能、与其它类的关系等。
|
||
格式：
|
||
```php
|
||
/**
|
||
* 〈一句话功能简述〉
|
||
* 〈功能详细描述〉
|
||
* @author [作者]
|
||
* @version [版本号, YYYY-MM-DD]
|
||
* @see [相关类/方法]
|
||
* @since [产品/模块版本]
|
||
* @deprecated
|
||
*/
|
||
```
|
||
> 说明：描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，`@since` 表示从那个版本开始就有这个类或者接口，`@deprecated` 表示不建议使用该类或者接口。
|
||
|
||
示例：
|
||
```php
|
||
/**
|
||
* LogManager 类集中控制对日志读写的操作。
|
||
* 全部为静态变量和静态方法，对外提供统一接口。分配对应日志类型的读写器，读取或写入符合条件的日志纪录。
|
||
* @author 张三，李四，王五
|
||
* @version 1.2, 2001-03-25
|
||
* @see LogIteraotor
|
||
* @see BasicLog
|
||
* @since CommonLog1.0
|
||
*/
|
||
```
|
||
|
||
#### 5.类属性、公有和保护方法注释：写在类属性、公有和保护方法上面。用 `// ` 来注释,需要对齐被注释代码。
|
||
示例：
|
||
```php
|
||
// 注释内容
|
||
private String logType
|
||
```
|
||
|
||
#### 6.成员变量注释内容：成员变量的意义、目的、功能，可能被用到的地方。用 `// ` 来注释，需要对齐被注释代码。
|
||
|
||
#### 7.公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
|
||
格式：
|
||
```php
|
||
/**
|
||
* 〈一句话功能简述〉
|
||
* 〈功能详细描述〉
|
||
* @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.避免在注释中使用缩写，特别是不常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。 |