PHP 注释

PHP 注释概念

在大多数编程语言中，注释以特定的语法结构或标记开始，以便编译器或解释器可以识别并忽略它们。注释的核心目的并非描述 “代码做了什么” —— 这一点代码本身应当清晰体现，而在于解释 “代码为什么这样实现”。

注释代码不仅能够向团队其他成员（或未来的自己）解释代码的意图、复杂的算法逻辑和做出的特殊决策，还能显著提升代码的可读性、可维护性以及可扩展性。良好的注释习惯有助于避免代码在繁琐的业务逻辑处理中变得越来越复杂和难以理解，从而确保项目在协作开发和后续版本迭代中保持清晰有序与高效开发。

/**
 *  ██╗  ██╗ █████╗ ██╗ ██████╗███████╗
 *  ██║ ██╔╝██╔══██╗██║██╔════╝██╔════╝
 *  █████╔╝ ███████║██║██║     ███████╗
 *  ██╔═██╗ ██╔══██║██║██║     ╚════██║
 *  ██║  ██╗██║  ██║██║╚██████╗███████║
 *  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝ ╚═════╝╚══════╝
 *
 *  开创者教程 · PHP 注释
 *  KAICZ.COM · PHP COMMENTS
 */

PHP 添加注释

在 PHP 中，注释是一种用于解释代码、提升可读性和便于维护的工具。PHP 支持三种注释语法：单行注释、多行注释和文档注释。

1. 单行注释

单行注释（//或#）用于注释单独一行代码，适用于简短说明、变量说明或行尾注释。

// 原始价格、计算用户折扣
$price = 99.99; // 商品原价，单位：元
$discount = $price * 0.1; # 目前固定为 9 折

2. 多行注释

多行注释（/* ... */）用于注释多行代码，适用于较长地说明或临时屏蔽大段代码。

function processData($input) {
    /*
    $result = complexAlgorithm($input);
    $result = validateOutput($result);
    $result = formatForDisplay($result);
    return $result;
    */

    // 简化版本
    return simpleProcess($input);
}

这样使用/* ... */可以快速注释掉多行代码，用于：临时禁用功能进行测试，调试时排除代码段，保留旧代码供参考。

3. 文档注释（DocBlocks）

文档注释（/** ... */）是最重要的注释类型，用于为PHP代码中的各种元素（如文件、类、方法等）提供结构化文档。

其包含以@开头的注释标记（如 @param, @return, @throws），IDE和文档生成器可以识别它们。

✅ 文件头的注释，用于说明文件的用途、作者、版权和依赖关系：

/**
 * 用户认证控制器
 *
 * 处理用户登录、注册、登出和密码重置等功能
 *
 * @package App\Http\Controllers
 * @copyright Copyright (c) 2024 Your Company
 * @license MIT License
 */

✅ 类的注释，类名及介绍：

/**
* 类的介绍
*
* 类的详细介绍（可选）。
* @author      alvin 作者
* @version     1.0 版本号
*/

✅ 函数的注释，函数作用，参数介绍及返回类型：

/**
* 函数的含义说明
*
* @access public
* @param mixed $arg1 参数一的说明
* @param mixed $arg2 参数二的说明
* @param mixed $mixed 这是一个混合类型
* @return array 返回类型
*/

PHP 注释标记

我们在平常写代码或看别人写的代码时, 在方法的说明注释中经常会有这样的注释:

/**
 * @param $num
 * @return array
 */

上面的 @param @return 就是注释标记

注释标记用于生成文档，param 指明需要接收的参数，return 指明返回值。

在使用phpDocumentor等工具生成文档时, 会识别相关注释, 而且 IDE 也会识别, 在编码的过程中会给出提示.

PHP 注释标记总结

• @api: 提供给第三方使用的接口
• @author: 标明作者
• @param: 参数
• @return: 返回值
• @todo: 待办
• @version: 版本号
• @inheritdoc: 文档继承
• @property: 类属性
• @property-read: 只读属性
• @property-write: 只写属性
• @const: 常量
• @deprecated: 过期方法
• @example: 示例
• @final: 标识类是终态, 禁止派生
• @global: 指明引用的全局变量
• @static: 标识类、方法、属性是静态的
• @ignore: 忽略
• @internal: 限内部使用
• @license: 协议
• @link: 链接,引用文档等
• @see: 与 link 类似, 可以访问内部方法或类
• @method: 方法
• @package: 命名空间
• @since: 从指定版本开始的变动
• @throws: 抛出异常
• @uses: 使用
• @var: 变量
• @copyright: 版权声明