PHP注释应是“上下文快照”，重在解释“为什么”：函数开头说明意图与决策依据，逻辑分支交代业务动因与技术约束，魔数标注来源依据，TODO须含截止时间、追踪号和根因。
注释不是代码的说明书，而是写给未来自己或同事看的“上下文快照”。PHP里加注释，关键不在多，而在准——准到能让人一眼看清“为什么这么写”，而不是“写了什么”。
函数开头：用注释交代意图，而非重复代码
别写// 计算用户积分这种和函数名calculateUserPoints()完全重复的注释。真正有用的是说明决策依据：
- 为什么用累加而非查表？——“因积分规则频繁变动，动态计算更易维护”
- 边界怎么处理？——“未登录用户返回0，不抛异常，前端统一兜底”
- 哪些参数是可选的？——“$bonus参数仅用于活动期，日常调用可省略”
逻辑分支处：注释要解释“跳转理由”，不是标注“这里是if”
在if ($user->isVIP() && $order->total > 500)后面，不要写// VIP大单走特殊流程。换成：
- “避免VIP用户等待超时：该路径绕过风控队列，但需人工复核”
- “此处不校验库存，因VIP专属商品已预占，库存服务异步同步”
让读代码的人立刻明白这个分支存在的业务动因和技术约束。
立即学习“PHP免费学习笔记（深入）”；
魔数与硬编码：用注释锚定来源，不是解释数值本身
遇到$timeout = 300;，别写// 超时5分钟。要写：
- “300秒：支付网关SLA要求最大响应时间（见文档v2.1第4.3节）”
- “12：微信小程序API限制单次上传文件数上限（2023年7月接口变更）”
把魔法数字变成可追溯的契约依据，而不是靠记忆猜。
临时方案与TODO：注释必须带截止线索
// TODO: 改用Redis缓存，当前MySQL查询太慢这类注释等于没写。改成：
- “// TODO: 2024-Q3前替换为Redis集群（已排期#TASK-892），当前SQL耗时>800ms（监控ID:sql_441）”
- “// HACK: 强制UTF-8转码（PHP 8.1 mbstring bug #GH-11222），待升级后移除”
没有时间点、没有追踪号、没有根因定位的TODO，只会堆成技术债雪球。
