1
0
mirror of https://gitee.com/tawords/tawords-docs synced 2025-01-27 03:00:28 +08:00
Code Issues Projects Releases Wiki Activity GitHub Gitee
tawords-docs/docs/manual/standard/2. 注释规范.md

118 lines
4.8 KiB
Markdown
Raw Normal View History

2021-08-07 15:56:20 +08:00
#### 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.避免在注释中使用缩写,特别是不常用缩写。说明:在使用缩写时或之前,应对缩写进行必要的说明。