注释规模

规则：源程序有效注释量必须在30％以上。

说明：由于每个文件的代码注释不一定都可以达到30%，建议以一个系统内部模块作为单位进行检查

文件头注释

规则：文件头部注释（文件最顶端）应包括文件名称、所属模块、创建人/修改人、版权等信息，以“/* */”符号标志。

说明：如果创建人与修改人不是同一个人，修改人应该添加上自己的修改信息（修改人、修改地方、日期等）

eg：

/*

* Fraction.class.php

* Fraction

*

* Created by Daniel on 2015-4-27

* Modify by Jacket on 2015-4-28:

* Fraction.setNumeratorAndDenominator

*

* Copyright (c) 2015年 __MyCompanyName__. All rights reserved.

*/

//引入分数（包括：分子、分母）接口定义

include_once('Printing.class.php');

类声明注释

规则：类和接口的注释放在class 或者 interface 关键字之前，include_once/require_once关键字之后，注释主要是一句话功能简述；类注释使用“/** */”注释方式，方便文档工具自动生成说明文档；“}”后要有注释，与“{”前类声明对应。

说明：如类声明

eg：

//引入分数（包括：分子、分母）接口定义

include_once('Printing.class.php');

/**

* 分数（包括：分子、分母）类定义，包括分数的构建、打印、计算等方法

*/

class Fraction implements Printing

{

。。。

}//class Fraction implements Printing

成员变量/常量注释

规则：成员变量/常量要通过注释说明其作用与用途；使用“/** */”注释方式，方便文档工具自动生成说明文档。

说明：注释单独成行，不要在成员变量/常量后面进行注释

eg：

class Fraction implements Printing

{

/**

* 分数的分子成员

*/

private $numerator;

/**

* 分数的分母成员

*/

private $denominator;

}//class Fraction implements Printing

成员方法注释

规则：定义方法时，要对其功能、参数、返回值分别进行注释；使用“/** */”注释方式，方便文档工具自动生成说明文档；“}”后要有注释，与“{”前方法声明对应。

说明：每个参数要用“@param”明确标记、而且标记要单独成行、没有参数时可省略，每个参数名与参数说明之间必须用空格“ ”分开，参数要说明类型、入参还是出参、用途等；返回要用“@return”明确标记、而且标记要单独成行、要说明类型、没有返回时也要标记清楚（void）、返回值意义要说清楚，构造/析构方法时可省略

eg：

/**

* 获得分数的分子

* @return integer

* 返回分子值

*/

public function getNumerator()

{

return $this->numerator;

}//public function getNumerator()

/**

* 设置分数的分子及分母

* @param integer $num [IN]分子值

* @param integer $den [IN]分母值

* @return void

*/

public function setNumeratorAndDenominator($num,

$den

)

{

$this->numerator = $num;

$this->denominator = $den;

}//public function setNumeratorAndDenominator($num,

其它注释

规则：注释时，使用‘|’来引用代码中的变量名及符号名，而不是使用引号来引用。

说明：

eg1:引用变量

// Sometimes we need |$count| to be less than zero

eg2：引用带引号符号

// Remember to call |stringWithoutSpaces("foo bar baz")|

规则：修改代码同时应修改相应的注释，以保证注释与代码的一致性，不再有用的注释要删除。

说明：略

规则：注释的内容要清楚、明了，含义准确，防止注释二义性。

说明：错误的注释不但无益反而有害

规则：避免在注释中使用缩写，特别是不常用缩写。

说明：在使用缩写时或之前，应对缩写进行必要的说明

规则：避免在一行代码或表达式的中间插入注释。

说明：容易使代码可理解性变差

eg:

避免如下注释

function setNumeratorAndDenominator($num/*分数的分子*/,$den)

规则：在代码的功能、意图层次上进行注释，提供有用、额外的信息。

说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息

eg：

// 如果从连结收到消息

if ($receiveFlag)

避免如下情况：

// 如果|$receiveFlag|为真

if ($receiveFlag)

规则：对关键变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档

规则：注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达，中文注释中需使用中文标点。

说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文

规则：方法内的单行注释使用“//”。

说明：调试程序的时候可以方便的使用 /* */ 注释掉一长段程序