PHP代码注释规范怎么定

wen PHP项目 2026-07-04 24

本文目录导读：

PHP代码注释规范怎么定

核心规范原则
不同类型注释的具体标准
常用 Tag 标签速查表
必须遵循的“不要”原则
工具与落地执行
总结：好的注释长什么样？

为 PHP 代码制定注释规范，核心目的是提高代码的可读性、可维护性以及便于自动生成 API 文档，通常遵循 PHPDoc 标准（基于的 DocBlock 块注释）。

以下是一套通用、实用的 PHP 代码注释规范建议，适合大多数中大型项目。

核心规范原则

必须使用 PHPDoc 格式：以开头，中间每行以开头。
关键节点必须注释：类、方法（函数）、属性、常量。
代码逻辑用行注释：或，仅用于解释复杂的业务逻辑（非必要不注释）。
保持简洁且准确：注释要随着代码更新而更新，避免误导。

不同类型注释的具体标准

文件头部注释（可选，但推荐）

用于说明文件包含的主要内容、版权信息。

<?php
/**
 * 文件名：UserService.php
 *
 * 描述：用户相关业务逻辑处理层
 *
 * @author     Zhang San <zhangsan@example.com>
 * @version    1.0.0
 * @copyright  2023 www.example.com
 * @license    MIT
 * @link       https://git.example.com/project/user-service
 * @since      File available since Release 1.0.0
 */

类注释

说明这个类的职责。不要写“这个类是用来...的”这种废话，直接陈述职责。

/**
 * 用户服务类
 *
 * 处理用户注册、登录、信息查询等业务逻辑。
 * 依赖 UserRepository 进行数据持久化操作。
 *
 * @package App\Services
 * @author   Li Si <lisi@example.com>
 */
class UserService
{
    // ...
}

属性注释

描述属性的数据类型和含义。

class User
{
    /**
     * 用户唯一标识符
     *
     * @var int|null 数据库自增主键，新记录可能为 null
     */
    private ?int $id = null;
    /**
     * 用户邮箱地址
     *
     * @var string 必填，需符合邮箱格式
     */
    private string $email;
    /**
     * @var string 用户类型：'admin' 或 'normal'
     */
    public string $role;
}

方法函数注释（最常用 & 最重要）

这是注释规范的核心,必须包含：

描述：方法实现的功能。
@param：参数名、类型、描述。
@return：返回值类型、描述。
@throws：可能抛出的异常。

/**
 * 根据用户ID查找用户并更新其邮箱
 *
 * @param  int         $id       用户ID，必须大于0
 * @param  string      $newEmail 新的邮箱地址，需通过格式验证
 *
 * @return bool|null             更新成功返回 true，用户不存在返回 false，
 *                               发生数据库异常返回 null
 *
 * @throws \InvalidArgumentException 当用户ID小于等于0或邮箱格式无效时抛出
 * @throws \RuntimeException         当数据库连接失败时抛出
 */
public function updateUserEmail(int $id, string $newEmail): ?bool
{
    if ($id <= 0 || !filter_var($newEmail, FILTER_VALIDATE_EMAIL)) {
        throw new \InvalidArgumentException('无效的用户ID或邮箱格式');
    }
    // ... 业务逻辑 ...
}

常量注释

用于解释常量的用途,尤其是当常量值是魔数或特殊字符串时。

class Status
{
    /**
     * 用户账户激活状态
     */
    public const STATUS_ACTIVE = 1;
    /**
     * 用户账户禁用状态
     */
    public const STATUS_DISABLED = 0;
}

行内注释

仅在需要解释复杂逻辑、算法或修复 Bug 的原因时使用。

public function calculateDiscount(float $price, string $vipLevel): float
{
    // 钻石会员享受 8 折优惠（基于产品部最新策略，2023-12-01 更新）
    if ($vipLevel === 'diamond') {
        return $price * 0.8;
    }
    // 普通会员不享受折扣（待产品确认后需修改此处逻辑）
    // return $price * 1.0;
    return $price;
}

常用 Tag 标签速查表

使用场景	示例
`@param`	方法参数	`@param string $name 用户名`
`@return`	返回值	`@return array\|null 用户数组或null`
`@throws`	可能抛出的异常	`@throws \PDOException 数据库错误`
`@var`	属性变量类型	`@var int`
`@see`	参考其他方法/类	`@see UserService::register()`
`@deprecated`	表明被弃用	`@deprecated 1.5.0 Use UserService::newMethod() instead`
`@since`	引入版本	`@since Version 2.0.0`
`@author`	作者	`@author Developer Name`
`@package`	所属包/模块	`@package App\Modules\Order`

必须遵循的“不要”原则

不要写显而易见的注释：

// 坏注释
// 获取用户
$user = getUser();
// 好注释（解释原因）
// 从缓存中获取用户，减少DB压力
$user = getUserFromCache($userId);

不要写与代码功能不一致的注释：注释过时比没注释更可怕。

不要为所有函数都写超长注释：简单的 Getter/Setter 可以一行搞定：

/**
 * @return string
 */
public function getName(): string
{
    return $this->name;
}

不要在函数内部写大段文档注释：内部逻辑使用或。

工具与落地执行

IDE 自动生成：在 PHPStorm（IntelliJ IDEA）中，输入后按回车，IDE 会根据函数签名自动生成 @param 和 @return 骨架，你只需填写描述。
代码规范检查工具：
- PHP_CodeSniffer：配置 MySource.Commenting 或 PSR-2/PSR-12 相关规则，检查 @param 是否缺失、类型是否匹配。
- PHP-CS-Fixer：自动修复注释格式（如对齐）。
- PHPMD：检测无效或不必要的注释。
生成 API 文档：使用 phpDocumentor 或 ApiGen，可根据标准的 PHPDoc 注释自动生成 HTML 格式的文档。

好的注释长什么样？

坏注释：

// 这是一个循环
for($i=0;$i<10;$i++){}

好注释：

/**
 * 发送批量通知
 *
 * 将待发送队列中的通知逐一发送给用户。
 * 此处使用循环是为了确保即使某一封发送失败，
 * 也不会阻塞后续邮件的投递。
 *
 * @param array $notifications 通知对象集合
 * @return int 成功发送的数量
 */
$successCount = 0;
foreach ($notifications as $notification) {
    // ... 发送逻辑 ...
    $successCount++;
}

遵循这套规范,你的 PHP 代码将不仅易于人类阅读，也能很好地与各种自动化工具集成。