## 通用注釋 ### 1. 文件的注釋通用樣例（普通程序文件，類文件，函數文件，變量定義文件） ~~~ /** * XXXXX的文件 * * 功能1： xxx * 功能2： xxx * * @file $Source: /home/doc/php開發注釋規范.md $ * @package core * @author Joy <anzhengchao@gmail.com> * @version $Id: php開發注釋規范.txt,v 1.1 2014/03/04 20:37:46 Joy Exp $ * @link http://www.joychao.cc */ ~~~ * @package 是團隊事先定義好的，在phpdocumentor里同一package的文件可以給出跟蹤的鏈接。項目開發前需要對其定義。 * @link 行后面接的地址是程序開發文檔的地址，因為我們目前沒有在線的程序開發文檔庫，所以可不加。 注意注釋的排版，左端保持對齊。 **說明：以上自動更新版本及文件名需要配置svn，具體請自行google 'SVN自動版本號'** ### 2. 普通函數注釋 ~~~ /** * 獲取頭像地址 * * @author Joy <anzhengchao@gmail.com> * * @param string $imageName 圖片文件名 * @param integer $size 大小 * * @return string */ function getAvatarUrl($imageName, $size = 80) { return sprintf(SITE_URL . '/service/images/cropped_%s/'.$imageName, $size); } ~~~ 順序按照author、param、return來放，區塊間空行。 ### 3. 程序段落注釋 段落注釋和邏輯注釋使用如下方式 ~~~ /** * 1 如果$_GET['do']等于buy,則購買條碼 */ if($_GET['do'] == 'buy') { // 1.1 驗證用戶提交變量是否合法 if($_POST['strCodeNum']) { } // 1.2 驗證用戶提交的碼是否可以購買 // 1.3 .................. } // end if /** * 2 如果$_GET['do']等于list,顯示用戶選擇的條碼 */ if($_GET['do'] == 'list') { // 2.1 驗證用戶提交變量是否合法 if($_POST['strCodeNum']) { } // 2.2 驗證用戶提交的碼是否可以購買 // 2.3 .................. } // end if ~~~