#### 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.避免在注释中使用缩写，特别是不常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。