PHP使用规范之一（注释与文档）

我会带着你远行 2022-04-10 03:26 202阅读 0赞

### 文章目录 ###

*   *   *  1 页面注释
         *  2 类注释
         *  3 函数注释
         *  4 变量注释
         *   *  4.1 类的成员变量
             *  4.2 特别有用的定义
             *  4.3 变量声明注释说明
         *  5 行注释

参考文档： [http://pear.php.net/manual/en/standards.sample.php][http_pear.php.net_manual_en_standards.sample.php]

### 1 页面注释 ###

/** * 当前页面功能描述 * * PHP version 5 //使用的PHP版本 * * @category 分类名称 * @package 包名称 * @author 作者名称 <作者邮箱> * @date 2018-12-12 * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_01.txt PHP License 3.01 * @version SVN: $Id$ * @link 访问地址 * @see NetOther, Net_Sample::Net_Sample() //相关联的其他类名 方法名 * @since File available since Release 1.2.0 //文件至哪个版本开始启用 * @deprecated File deprecated in Release 2.0.0 //文件哪个版本之后不推荐使用 */

> 页面功能描述、 `package`、`author`、`date`、`link` 这几个我觉得是比较需要的

### 2 类注释 ###

/** * 类的功能描述 * * @category 分类名 * @package 包名 * @author 作者名称 <邮箱> * @date 2018-12-12 * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_01.txt PHP License 3.01 //许可证 * @version Release: @package_version@ //版本 * @link 访问地址 * @see NetOther, Net_Sample::Net_Sample() //相关联的其他类名 方法名 * @since Class available since Release 1.2.0 //文件至哪个版本开始启用 * @deprecated Class deprecated in Release 2.0.0 //文件哪个版本之后不推荐使用 */

> 类功能描述、 `package`、`author`、`date`、`link` 这几个我觉得是比较需要的

### 3 函数注释 ###

/* * @todo 描述方法的作用 * @link 访问链接 文档链接 | 控制器方法访问链接 | 其他时候没有 * @author 作者名称 <邮箱> * @date 2018-12-12 * @param int $argName 参数说明 多个参数 多行 * @param 参数类型 参数名称 参数说明 * @return int 0|1 * @throws 触发异常描述 * @access public * @usage 使用方法说明 * */

其中 `todo`、`author`、`date`、`usage` 是自定义添加的，与规范无关

### 4 变量注释 ###

#### 4.1 类的成员变量 ####

/* * @var string $name */
    public $name = '';

#### 4.2 特别有用的定义 ####

> 有时候，我们使用IDE 按住ctrl 点击某个函数就能自动进入到对应的方法定义位置  
> 但是并不是所有的方法定义都很明显，比如

$uid = 1;
    $model = model('Home/Member');
    $user_info = $model->getUserInfo($uid);

> 如果我们 ctrl 点击`getUserInfo` 方法会发现毫无反应  
> 加入注释：

$uid = 1;
    /* @var \App\Home\Model\Member $model */
    $model = model('Home/Member');
    $user_info = $model->getUserInfo($uid);

> 我们发现 这样就能轻松的进入定义位置

#### 4.3 变量声明注释说明 ####

/* @var 变量类型 变量名称 */

### 5 行注释 ###

> 有时候，代码的逻辑异常复杂，如果仅仅在函数头部声明一下，很难让人理解  
> 这时候可能需要加入 行分步注释（我自定义的 不是规范）

/***************** 1. 如果分数大于90 且是男生 ********************/
    if ($score > 90 && $gender == 'male')
    { 
    	
    }
    /***************** 2. 如果分数大于85 且是女生 ********************/
    elseif ($score > 85 && $gender == 'female')
    { 
    	
    }

> 当然简单的变量注释可使用

$gender = 'male'; //性别 male 男 female 女

[http_pear.php.net_manual_en_standards.sample.php]: http://pear.php.net/manual/en/standards.sample.php