PHP注释是团队协作的“接口说明书”，需遵循PHPDoc规范：方法注释明确功能、参数、返回值及异常；类注释定义核心职责与约束；属性标注类型与业务含义；行内注释仅解释非常规逻辑；TODO须带责任人与时限；通过PHPStan、PHPCS等工具自动化校验并落地执行。
PHP注释不是可有可无的装饰，而是团队协作的“接口说明书”。写得清楚、格式统一、位置恰当的注释，能大幅降低新成员上手成本，减少重复提问，避免因误解逻辑引发的低级Bug。
函数/方法注释：用PHPDoc规范描述“做什么、要什么、给什么”
每个公开（public）或受保护（protected）的方法，都应以标准PHPDoc块开头。重点说明功能目的、参数类型与含义、返回值类型与意义、可能抛出的异常。
- 使用@param明确每个参数的类型（如string|int|array）和用途，避免只写“$id 用户ID”这种模糊描述，改成“$id 用户唯一标识，整数类型，不可为null”
-
@return必须注明具体类型，如array
或?User（表示可能返回User对象或null） - 不鼓励在注释里写“TODO”或“FIXME”，这类标记应进入项目管理工具（如Jira），注释只保留稳定、准确的契约信息
类与属性注释：讲清“身份”与“边界”
类注释需一句话定义其核心职责（例如：“订单状态处理器，负责校验、变更及事件分发”），而非复述类名。关键属性（尤其是public或被序列化/导出的）必须标注类型和业务含义。
- 对public $status，不要只写“状态”，而应写“订单当前生命周期状态，取值范围：pending|confirmed|shipped|cancelled”
- 使用@var标注属性类型，尤其当PHP类型声明未覆盖（如PHP 7.4+支持private array $items;，但复杂嵌套结构仍建议加注释说明）
- 避免在类注释中罗列所有方法——那是IDE和文档生成器的工作；注释聚焦“为什么存在”和“不可违反的约束”
行内注释与TODO处理：只解释“非常规”，不解释“显而易见”
行内注释（// 或 /* */）应仅用于解释**违背直觉、绕过常规逻辑、临时妥协或隐藏副作用**的代码段。
立即学习“PHP免费学习笔记（深入）”；
- ✅ 好例子：// 因支付网关限制，金额需乘100转为分单位传入
- ❌ 坏例子：// 循环遍历用户数组（代码本身已清晰表达）
- 所有// TODO:必须带责任人和预期完成时间，如// TODO(@zhangsan): 2024-Q3 支持多币种结算（见#PAY-123），并纳入每日站会跟踪
自动化检查与团队落地：让规范真正“活”起来
再好的约定，没有工具兜底就会退化。推荐在CI流程中集成PHPStan + PHP_CodeSniffer + phpDocumentor基础校验。
- 用phpcs强制检查PHPDoc完整性（如缺失@param/@return）、缩进与空格风格
- 用PHPStan结合注释类型推断，发现实际代码与注释类型不一致的问题（例如注释写@var User，但实际赋值了string）
- 新成员入职时，提供一份精简版《注释速查卡》（含模板、反例、CI报错解读），比长篇文档更易执行
