注释应解释“为什么”而非“做了什么”。✓ 好例子说明业务约束：// 因支付网关不支持小数，金额统一转为分单位处理；✗ 差例子复述代码：// 循环遍历数组。
因为注释不是写给机器看的，是写给人看的——可很多人只写了“做了什么”，没写“为什么这么做”。
注释要回答“为什么”，而不是复述“做了什么”
比如 // $i++ 这种注释毫无价值，代码本身已经说清了动作。真正需要解释的是背后的逻辑断点、业务约束或临时妥协。
- ✓ 好例子：
// 因支付网关不支持小数，金额统一转为分单位处理 - ✗ 差例子：
// 循环遍历数组（for ($i = 0; $i - 遇到魔数、硬编码、绕过校验等非常规写法时，必须补上原因，否则接手的人第一反应是“这怕不是bug”
函数开头用 DocBlock 交代契约，而非罗列参数
PHPDoc 不是装饰品，是接口说明书。重点不是“这个函数有3个参数”，而是“调用者该信什么、不该信什么、出错时怎么处理”。
- 必须写
@param类型和含义（如@param string $format 支持 'json' 或 'xml'，不区分大小写） - 必须写
@return的实际行为（如@return array|null 返回用户数据，查不到时返回 null 而非空数组） -
@throws要具体（@throws InvalidArgumentException 当 $id 为空字符串时抛出），别只写@throws Exception
关键分支加内联注释，尤其 if/else 和异常路径
逻辑越反直觉，越需要注释锚定意图。特别是兜底、降级、兼容旧版等“看起来像补丁”的代码。
立即学习“PHP免费学习笔记（深入）”；
- 在
if (is_null($user)) { ... }前写：// 兼容v1老数据：部分记录未关联用户，按游客身份处理 - 在
catch (ApiTimeoutException $e) { return defaultResponse(); }后加：// 网关超时不可重试，返回缓存结果保证可用性 - 避免写“如果失败就跳过”，而要说明“为何可以跳过”
删掉过期注释，比不写更危险
代码重构后留着旧注释，等于埋下误导性路标。发现注释和代码对不上，优先怀疑注释，再确认代码逻辑是否已变。
- 每次修改逻辑后，顺手扫一眼附近注释——它还站得住脚吗？
- 看到
// TODO: 优化此处超过两周没动，要么删掉，要么立刻做，别让它变成背景噪音 - 版本控制里搜
git log -S "FIXME"，定期清理技术债标记
注释不是代码的附属品，是协作契约的一部分。写的时候多问一句：“三个月后的我，或刚入职的同事，能凭这行字准确还原当时的决策吗？”
