注释规范
每个程序均必须提供必要的注释，书写注释要求规范，参照PEAR提供的注释要求，为今后利用phpdoc生成 PHP 文档做准备。
1、程序头注释块
每个程序头部必须有统一的注释块，规则如下：
a．必须包含本程序的描述；
b．必须包含作者；
c．必须包含书写日期；
d．必须包含版本信息；
e．必须包含项目名称；
f．必须包含文件的名称；
g．重要的使用说明，如类的调用方法、注意事项等；
参考例子如下：
~~~``
//
// +---------------------------------------------------------+
// | PHP version 4.0
// +---------------------------------------------------------+
// | Copyright (c) 1997-2001 The PHP Group
// +---------------------------------------------------------+
// | This source file is subject to of the PHP license,
// | that is bundled with this packafile LICENSE, and is
// | available at through the world-web at
// | http://www.php.net/license/2_02.txt.
// | If you did not receive a copy of the and are unable to
// | obtain it through the world-wide-web,end a note to
// | [email protected] so we can mail you a immediately.
// +---------------------------------------------------------+
// | Authors: Stig Bakken
// | Tomas V.V.Cox
//
// +———————————————————+
//
// $Id: Common.php,v 1.8.2.3 2001/11/13 01:26:48 ssb Exp $
##2、类的注释
类的注释采用里面的参考例子方式：/**
- @ Purpose:
- 访问数据库的类，以ODBC作为通用访问接口
- @Package Name: Database
- @Author: Forrest Gump [email protected]
- @Modifications:
- No20020523-100:
- odbc_fetch_into()参数位置第二和第三个位置调换
- John Johnson [email protected]
- @See: (参照)
*/
class Database {
...
}
3、函数和方法的注释
函数和方法的注释写在函数和方法的前面，采用类似下面例子的规则：
/**
* @Purpose:
* 执行一次查询
* @Method Name: query()
* @Param: string $queryStr SQL查询字符串
* @Param: string $username 用户名
* @Access: public
* @Return: mixed 查询返回值（结果集对象）
*/
public function query （ $queryStr, $username ） {
...
}4、变量或者语句注释
程序中变量或者语句的注释遵循以下原则：
a．写在变量或者语句的前面一行，而不写在同行或者后面；
b．注释采用/* */的方式；
c．每个函数前面要包含一个注释块。内容包括函数功能简述，输入/输出参数，预期的返回值，出错代码定义；
d．注释完整规范；
e．把已经注释掉的代码删除，或者注明这些已经注释掉的代码仍然保留在源码中的特殊原因。
例子：
/**
* @Purpose:
* 数据库连接用户名
* @Attribute/Variable Name: db_user_name
* @Type: string
*/
var db_user_name;5、标注使用
IDE支持一些特殊注释，可以列出整个项目的特殊注释，方便后期的维护和代码检查，例如：
//@fixMe 表示需要修复项。如：修复了IP获取的一个安全漏洞
//@todo 表示需要完善的地方。如：这个函数的效率太低，需要改进。 上述注释和java中的标注及注解比较相像。可以查看NetBeans中标注的效果。
不同的IDE对这类特殊注释的支持程度不一。为了编码效率和团队协作，建议在项目开发时使用IDE进行项目管理。
对于代码不推荐使用的函数或方法，使用@Deprecated注释；对于重载方法，使用@over load注释。