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