<p>PHP注释是提升代码可读性、可维护性与协作效率的关键，分为单行（//或#）、多行（/ /）和文档型（/* /）三类，需准确表达“为什么”而非“做什么”，并随代码同步更新。</p>
PHP注释不是可有可无的装饰，而是团队协作中降低沟通成本、提升代码可维护性的关键环节。写得清楚、统一、有信息量的注释，能让同事快速理解你的意图，也能让未来的你少花半小时去“破译”自己写的逻辑。
函数/方法注释：用PHPDoc规范说明用途与参数
每个公开方法（public）都应配以标准PHPDoc注释块，放在函数声明正上方。它不只是写“这个函数做啥”，更要说明输入、输出、异常和业务约束。
- 用@param明确每个参数类型和含义，比如@param string $email 用户邮箱，需已验证
- 用@return注明返回值类型及特殊情形，如@return array|false 成功返回用户数据，失败返回false
- 必要时加@throws说明可能抛出的异常，方便调用方做兜底
- 避免空泛描述，例如“处理用户数据”不如“根据user_id查询并返回脱敏后的基础资料（不含手机号）”
行内注释：只解释“为什么”，不重复“做什么”
代码本身已清晰表达操作时，别写“把$id赋值给变量”这类废话。行内注释（// 或 #）只用于补充上下文或说明取舍原因。
- 解释绕过常规逻辑的原因：// 因第三方API暂不支持分页，此处采用全量拉取后本地过滤
- 标记临时方案或待优化点：// TODO: 后续接入缓存层，当前直连DB（2024-Q3排期）
- 提醒潜在风险：// 注意：此处未校验$amount是否为负数，上游已保证合法性
- 避免在复杂表达式旁堆砌注释，优先考虑拆解变量或提取函数
类与属性注释：厘清职责边界与数据契约
类注释说明整体定位与使用场景；属性注释则聚焦其业务语义与生命周期约束，尤其对public或protected属性不可省略。
立即学习“PHP免费学习笔记（深入）”；
- 类头注释写清“谁用、怎么用、不能怎么用”，例如@package App\Services\Payment + 简要说明适用支付渠道范围
- 属性用@var标注类型，对数组明确键值结构：@var array<string, int> 订单状态映射表，key=状态码，value=重试次数
- 敏感字段加安全提示：@var string 加密存储的token，仅限内部服务间透传
- 避免在private属性上过度注释——若需说明，往往意味着职责过重，建议重构
团队落地小贴士：从工具到习惯
再好的规范，没人执行就是废纸。推动落地靠三件事：工具辅助、CR把关、轻量复盘。
- 在IDE中启用PHPStan或PHP_CodeSniffer，配置检查@param缺失、类型不匹配等硬性问题
- Code Review时把注释质量列入checklist，重点看是否准确、是否冗余、是否过时
- 每月抽1个典型PR，匿名展示“好注释”和“差注释”对比，不批评人，只讲效果差异
- 新成员入职第一周，安排ta给一个老模块补全PHPDoc，既是熟悉代码，也是建立共识
