Question

通用注释

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