## 通用注释 ### 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 ~~~