php开发注释规范(简化易实施版)
2007-11-13 返回首页
一、文件的注释通用样例（普通程序文件，类文件，函数文件，变量定义文件）
/**
* 购买条码的文件
* 功能1：
* 功能2：
*
* @file $Source: /home/cvs/sitesdocument/系统管理/php开发注释规范.txt,v $
* @package ewmcc.i139.cn_buy_code
* @author 熊超 <xiongchao@gmedia.cn>
* @version $Id: php开发注释规范.txt,v 1.1 2007/08/07 10:37:46 xiongc Exp $
* @link http://www.baidu.com
*/
@file行在提交了cvs之后，会自动被补充为如下样式：
* @file $Source: /home/cvs/sitesdocument/系统管理/php开发注释规范.txt,v $
@version行在提交了cvs之后，会自动被补充为如下样式：
* @version $Id: php开发注释规范.txt,v 1.1 2007/08/07 10:37:46 xiongc Exp $
@package是团队事先定义好的，在phpdocumentor里同一package的文件可以给出跟踪的链接。项目开发前需要对其定义。
@link行后面接的地址是程序开发文档的地址，因为我们目前没有在线的程序开发文档库，所以可不加。
注意注释的排版，左端保持对齐。
二、类的注释，使用如下几个tag
/**
* 条码及相关操作对应的类
* 功能1：
* 功能2：
*
* @author 熊超 <xiongchao@gmedia.cn>
* @access public
* @abstract
*/
public class ab
{
}
@access (public|private) 标记类是私有的还是公用的。
@abstract标记该类是个抽象类
虽然我们使用的是php5，但目前程序类的编写仍然沿用的php4，因此@access和@abstract两项可加可不加。
三、类的变量定义
public class ab
{
/**
* 记录总数。
* @var integer
*/
var $intTotalNum;
}
四、普通函数和类中的函数注释
/**
* 返回某用户名是否能购买$intCodeNum个条码
*
* @author 熊超 <xiongchao@gmedia.cn>
* @global object $db 数据库链接
* @param integer $intCodeNum 条码个数
* @param string $strUserName 用户名
* @return boolean 返回true or false
*/
function ab($intCodeNum, $strUserName)
{
// 引用全局变量
global $db;
}
顺序按照author、global、return来放。
五、程序段落注释
段落注释和逻辑注释使用如下方式
/**
* 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