**每個程序均必須提供必要的注釋，書寫注釋要求規范，參照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
// | license@php.net 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 gump@crtvu.edu.cn
* @Modifications:
* No20020523-100:
* odbc_fetch_into()參數位置第二和第三個位置調換
* John Johnson John@crtvu.edu.cn
* @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注釋。
