PHP 注释规范遵循PSR吗

wen PHP项目 2026-08-11 2

本文目录导读：

PHP 注释规范遵循PSR吗

没有专门的 PSR 注释标准
现有 PSR 中的相关建议
社区实际遵循的“事实标准”（非 PSR，但推荐）
总结与建议

PSR 标准没有专门针对“注释”的强制性规范，但 PSR-1 和 PSR-2（以及 PSR-12 修订版）对注释有一些建议性指导。

情况如下：

没有专门的 PSR 注释标准

PHP-FIG（PHP 标准组）发布的标准中，并没有一个叫 PSR-XX: Docblock 标准 的文件，他们的关注点主要在代码风格（缩进、括号位置）、自动加载、接口规范等。

现有 PSR 中的相关建议

虽然不强制,但 PSR 规范中提到了注释的要求，必须遵守：

PSR-1（基础编码标准）：
- 明确要求： PSR-1 明确规定，文件必须使用 <?php 长标签，并且文件必须只使用 UTF-8 编码（无 BOM），这通常是对整个文件（包括注释）的要求，如果注释中有 BOM 或特殊字符，会导致报错。
PSR-2（编码风格指南）与 PSR-12（扩展编码风格）：
- 关于注释的段落： PSR-2/12 提到，注释和 DocBlock 应遵循相关工具（如 phpDocumentor）的格式（这算是一种隐性的指引）。
- 实际硬性要求（代码层面）： 注释主要影响代码行的长度限制，PSR-2/12 规定：
  - 代码行（包括注释行）建议不超过 120 个字符。
  - 硬性限制是 必须不超过 80 个字符（除非是导入的类名或常量）。
  - 也就是说,注释行不能超过 80 个字符，否则视为不符合规范。

社区实际遵循的“事实标准”（非 PSR，但推荐）

既然 PSR 没写，PHP 社区实际上强依赖 PHPDoc（基于 phpDocumentor 的标签语法）作为事实标准，这是 IDE（如 PhpStorm、VSCode）识别类型提示、生成文档的基础。

类、方法、属性：使用块注释。
常用标签：@param、@return、@throws、@var 等。
类型强制：这些标签中的类型提示（如 array、string、ClassName）通常会配合 IDE 的静态分析，虽然这不属于 PSR，但属于现代 PHP 开发的必要条件。

总结与建议

如果你问“注释规范是不是必须遵循 PSR”，答案是：

遵守 PSR 的关键在于格式：行宽限制、编码格式、标签写法是必须的。
内容描述是关键：PSR 不关心你写什么文字，只关心格式友好，因此推荐使用 PHPDoc 格式来写，这符合 PSR-12 中“应遵循相关文档工具规范”的精神，也能让 IDE 正常识别。

一个符合 PSR-12 规范的注释范例：

<?php
declare(strict_types=1);
namespace App\Service;
/**
 * 处理用户注册逻辑的示例类。
 *
 * 该类负责验证用户输入并调用仓库层保存数据。
 *
 * @package App\Service
 */
final class UserRegisterService
{
    /**
     * 注册新用户。
     *
     * @param string $name     用户名（最大长度 50 字符）。
     * @param string $email    邮箱地址，必须唯一。
     * @param string $password 明文密码（将在内部进行哈希处理）。
     *
     * @return int 注册成功后的用户 ID。
     *
     * @throws \InvalidArgumentException 当邮箱格式不正确时抛出。
     */
    public function register(string $name, string $email, string $password): int
    {
        // 业务逻辑代码
        // 注意这行注释不能超过 80 个字符（虽然推荐控制在 120 以内），若超出需换行。
        return 1;
    }
}