PHP项目代码注释如何规范编写维护

本文目录导读：

1. 注释的类型与使用场景
2. PHPDoc 规范（核心）
3. 团队注释约定（容易忽略但重要）
4. 长期维护注释的策略
5. 快速自查清单

为 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
 */

---

团队注释约定（容易忽略但重要）

1. 注释只说“为什么”，不说“是什么”

   • ❌ // 将变量 $a 赋值为 5
   • ✅ // 默认分页大小，超过该值会触发性能警告

2. 类型标注优先于注释
   能用 PHP 类型声明（int、string、?User、array<int,string>）的就不要写在注释里。

   • 好的写法：public function find(int $id): ?User
   • 多余的注释：@param int $id（IDE 已从类型声明中知道）

3. 废弃方法必须加 @deprecated 并说明替代方案

4. 避免模板化注释
   不需要给每个 getter/setter 都写一长串,除非有特殊逻辑。

5. 敏感操作要加警告

   /**
    * 删除用户（不可逆操作！）
    * 会同时移除该用户的订单、评论等关联记录。
    * 请在操作前二次确认。
    */

---

长期维护注释的策略

把注释纳入代码审查（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）来自动检查注释格式，这样团队的注释风格就会统一,文档维护成本也会大大降低。