PHP注释常常被开发者视为“写完即忘”的附加环节，然而，经历过大型项目维护的人深知，它是项目可维护性、团队协作效率与长期代码质量的基石。一份清晰、统一且位置恰当的注释，能让新成员在30分钟内快速理解核心逻辑，让半年后的自己不再因代码而困惑，也能让静态分析工具真正发挥作用。以下是从实战中沉淀出的注释添加规范，内容务实，不空谈理论。
写注释不是写小说，但也并非写天书。关键在于把“它做什么”“需要什么”“返回什么”“可能出什么错”讲清楚，而不是重复代码本身。下面从几个层面详细展开。
函数/方法注释：使用PHPDoc规范描述行为与契约
每个公开（public）或受保护（protected）的方法，都应添加完整的PHPDoc块，位置紧贴函数声明正上方。重点在于明确“行为契约”——不要写“本函数处理用户登录”，而应写“验证用户凭据并生成会话令牌，失败时抛出AuthenticationException”。这样IDE和文档生成工具才能准确理解你的意图。
- 使用
@param标注每个参数的类型和业务含义，例如@param string $email 用户注册邮箱，需已通过格式校验 - 用
@return明确返回值类型和业务语义，例如@return array{token: string, expires_at: int} 成功时返回含JWT令牌及过期时间戳的关联数组 - 异常情况标注
@throws，例如@throws InvalidInputException 当邮箱格式非法或密码长度不足 - 避免冗余信息：
@author和@since等由Git管理，注释中只保留运行时必需的内容。
关键逻辑块注释：解释“为什么”，而非“是什么”
在if判断前、循环体内、复杂算法步骤间，添加简短的行内注释（//）或块注释（/* */），聚焦于设计意图和边界考量。简单来说：不要解释代码在做什么（代码本身已经足够清晰），而是解释你当时为何要这样写。举例说明：
- 在
if ($user->getLoginCount() > 5 && time() - $user->getLastLoginAt()前面加// 防爆破：1小时内登录失败超5次即临时锁定账号 - 在SQL查询拼接后面写
// 注意：此处未使用预处理因$sortField来自白名单配置，非用户输入 - 跳过某段旧逻辑时注明
// TODO: 待迁移至新支付网关后移除此兼容分支（当前仍需支持LegacyBank API v2）
文件与类注释：一句话定义职责边界
每个PHP文件顶部使用PHPDoc声明文件用途；每个类开头使用PHPDoc说明其核心职责与使用场景。不要写“用户相关操作类”这种过于笼统的描述，而要指出“负责用户生命周期管理，包括注册审核、角色变更、软删除及数据导出合规处理”。
- 文件注释中通过
@package标明模块归属（如App\Payment），便于IDE导航和文档自动生成 - 类注释中若涉及重要约束，直接写在注释里，例如
@see UserStatusTransitionRule 该类不校验状态流转合法性，调用方须自行确保 - 接口（interface）注释必须说明实现类应满足的行为契约，例如
@method void notify(string $event, array $payload) 同步触发事件，实现类不得阻塞主线程
注释维护纪律：和代码一样纳入CR与CI流程
注释不是写完后就不再更新的快照，而是会随代码演进持续更新的活文档。将注释质量纳入Code Review检查清单，在CI中接入phpstan或php-cs-fixer来检查基础规范（例如PHPDoc缺失、@param类型不匹配）。
- PR描述中要求填写“本次修改涉及哪些注释更新”，强制开发者思考变更是否影响对外契约说明
- 对于自动生成文档（如Swagger或PHPDocumentor）所使用的注释，设置CI任务验证其语法有效性，失败则阻断合并
- 定期（每季度）用工具扫描
@todo、@fixme标记，清理过期条目或将其转为正式任务
归根结底，注释是一种投资——前期多花几分钟把话说清楚，后期就能省下几小时甚至几天的排查时间。请记住：好的注释让你和同事都能安心入眠。
