本文目录导读：
为 PHP 项目编写规范的代码注释，不仅能提高代码的可读性，还能借助工具自动生成 API 文档、辅助 IDE 进行智能提示，下面从注释类型、PHPDoc 规范、团队约定和维护策略四个方面来说明。
注释的类型与使用场景
PHP 注释主要分为三种：
单行注释（）
- 用途：解释某一行或局部代码的逻辑，解决“为什么要这样写”。
- 示例：
// 如果用户未登录，重定向到登录页 if (!isset($_SESSION['user_id'])) { header('Location: /login'); exit; }
多行块注释（）
- 用途：临时禁用代码块,或对一段逻辑进行整体说明。
- 示例：
/* * 该段代码用于处理第三方回调 * 注意：此处的签名验证必须放在第一步 */
文档注释（）
- 用途：用于类、方法、属性、常量、函数的正式说明，遵循 PHPDoc 标准。
- 示例：
/** * 根据用户 ID 获取用户信息 * * @param int $userId 用户主键ID * @param bool $withDeleted 是否包含已软删除的记录 * @return User|null 返回 User 对象，未找到时返回 null * @throws InvalidArgumentException 当 userId 小于 1 时抛出 */ public function findUser(int $userId, bool $withDeleted = false): ?User { // ... }
PHPDoc 规范（核心）
这是现代 PHP 项目最常用的注释规范，IDE（如 PhpStorm、VS Code）和工具（phpDocumentor、phpstan、Psalm）都能识别。
类注释
/**
* 用户相关业务逻辑处理类
*
* 负责用户的注册、登录、信息查询与更新。
* 所有涉及密码的操作会先经过 PasswordHasher 加密。
*
* @package App\Services
* @author 张三 <zhangsan@example.com>
* @since 2.0.0 新增软删除支持
*/
class UserService
{
}
方法/函数注释
| 用途 | 示例 | |
|---|---|---|
@param |
参数说明 | @param string $email 用户邮箱 |
@return |
返回值说明 | @return array<string, mixed> |
@throws |
可能抛出的异常 | @throws \RuntimeException 当数据库连接失败 |
@deprecated |
标记废弃方法 | @deprecated 3.0.0 请使用 createUser() 替代 |
@see |
相关链接/方法 | @see \App\Services\UserNotifier |
完整示例：
/**
* 为指定角色批量分配权限
*
* 此操作会先清空该角色现有权限，再插入新权限（事务保护）。
*
* @param int $roleId 角色 ID，必须存在于 roles 表
* @param int[] $permissionIds 权限 ID 数组
* @param bool $syncParent 是否同步子角色的权限（默认 false）
*
* @return bool 操作成功返回 true，失败返回 false
*
* @throws \App\Exceptions\RoleNotFoundException 角色不存在
* @throws \App\Exceptions\PermissionNotFoundException 某个权限 ID 无效
* @throws \PDOException 数据库事务失败
*/
public function assignPermissions(int $roleId, array $permissionIds, bool $syncParent = false): bool
{
// ...
}
属性/常量注释
/** * 用户模型对应的数据表名 * * @var string */ protected string $table = 'users'; /** * 系统版本号（语义化版本格式） * * @deprecated 请使用 \App\AppInfo::VERSION */ const VERSION = '2.3.1';
文件头部注释（可选）
对于模块入口、控制器文件,可包含版权与简要说明：
/** * 用户管理模块控制器 * * @copyright 2024 Your Company * @license MIT * @link https://docs.example.com/user-module */
团队注释约定（容易忽略但重要）
-
注释只说“为什么”，不说“是什么”
- ❌
// 将变量 $a 赋值为 5 - ✅
// 默认分页大小，超过该值会触发性能警告
- ❌
-
类型标注优先于注释
能用 PHP 类型声明（int、string、?User、array<int,string>）的就不要写在注释里。- 好的写法：
public function find(int $id): ?User - 多余的注释：
@param int $id（IDE 已从类型声明中知道）
- 好的写法：
-
废弃方法必须加
@deprecated并说明替代方案 -
避免模板化注释
不需要给每个 getter/setter 都写一长串,除非有特殊逻辑。 -
敏感操作要加警告
/** * 删除用户（不可逆操作！） * 会同时移除该用户的订单、评论等关联记录。 * 请在操作前二次确认。 */
长期维护注释的策略
把注释纳入代码审查（Code Review）
- 审查时检查：注释是否准确？是否与方法签名矛盾？
- 发现
@param参数名拼错或类型不匹配,必须要求修正。
利用静态分析工具
- PHPStan / Psalm：可以配置强制要求公共方法有注释：
// phpstan.neon parameters: reportUnmatchedPropertyType: true checkMissingClosureDocComment: true - phpDocumentor / phpdoc-parser：自动生成 API 文档,促使团队保持标准。
与 IDE 联动
- 使用
@see、@link增加跳转能力。 - 安装 PhpStorm 的 PHPDoc 自动填充插件,快速生成模板。
重构时同步更新注释
- 修改方法签名（参数类型、返回值）后，必须同步更新
@param和@return。 - 建议使用 IDE 的“重构”功能,它通常能自动更新部分注释。
定期清理过时注释
- 使用 Git Blame 或
@deprecated标记长期未更新的注释。 - 每个版本迭代时，花 30 分钟批量删除以下无意义注释：
// 获取数据 $data = $this->fetch();
快速自查清单
| 检查点 | 标准 |
|---|---|
所有 public 方法 |
至少有 @param（参数多时）、@return、@throws |
| 复杂私有方法 | 至少有一行说明“为什么这么做” |
| 魔术方法 | 必须在类注释中说明 |
| 常量/静态属性 | 如果含义不直观，必须加注释 |
| TODO/FIXME | 关联对应的 issue 编号，如 // TODO: #123 支持批量删除 |
| 类型信息 | 优先用 PHP 类型声明，注释只补充额外说明 |
掌握以上规范后，可以用 php-cs-fixer 或 PHP_CodeSniffer 配合规则集（如 @PSR12、@PHPDoc）来自动检查注释格式，这样团队的注释风格就会统一,文档维护成本也会大大降低。
