注释规范

不写不必要的注释，只有当代码不能很好地说明逻辑时，才用注释补充；把注释看成程序的一部分，在编写/维护代码时同时编写/维护注释；注释完全采用 PHPDocumentor 的规范，以方便用其生成API 级文档。下边给出各个部分的注释示范。

1 文件头注释

注释包括：

• 项目、模块名称，文件名称、功能说明；
• 模块或文件的使用说明；
• 作者、日期；
• 修改记录。

示范：

<?php
/****************************************
* 项目名称：ZMedia 数据抓取服务
* 文件名称：ZMedia_Spider.php
* 文件功能：服务运行入口
*****************************************
* 运行方式：php ./ZMedia_Spider.php [-s] [控制信号] [-d]
* 参数说明：
* -s 控制信号：start(开始运行)、stop(结束运行)、restart(重新启动)
* -d 调试状态，终端窗口显示输出调试信号，无则无窗口运行输出到日志
*
* 如：php ./ZMedia_Spider.php -s restart -d debug
*
*****************************************
* 创建日期：2021-05-01
* 创建作者：张三
*****************************************
* 修改记录：
* 2021-05-01，V1.0，创建文件
****************************************/

2 类注释

注释包括：

• 类名称
• 作者、日期；
• 修改记录。

示范：

<?php
/*****************************************
* 文件功能：日志记录类
*****************************************
* 创建日期：2021-05-21
* 创建作者：张三
*****************************************
* 修改记录：
* 2021-05-21，V1.0，创建文件
****************************************/

3 函数/类方法注释

注释包括：

• 函数/类方法的功能说明；
• 输入参数说明；
• 输出结果说明；
• （可选）实现流程说明。

示范：

/***********************************************************
* 功能：PHP 截取UTF-8 字符串，解决半字符问题。
* 说明：英文、数字（半角）为1 字节（8 位），中文（全角）为3 字节
************************************************************
* 输入：$str 源字符串
* $len 左边的子串的长度
* 输出：取出的字符串, 当$len 小于等于0 时, 会返回整个字符串
************************************************************/
function utf_substr($str, $len)