注释是让逻辑可被理解的关键桥梁；单行注释用//说明意图，多行注释用/.../概括一段逻辑，PHPDoc以/**开头供工具识别，真正有用的注释只解释“为什么”。
注释不是代码的附属品，而是让逻辑可被理解的关键桥梁。写得清楚的注释，能让别人（包括未来的你）三秒看懂一段逻辑的意图，而不是花三分钟猜它在做什么。
单行注释：用对地方，别堆砌
用 // 或 # 快速说明某一行或相邻几行的用途，比如变量含义、临时开关、分支判断依据。
- // 是主流写法，几乎所有编辑器都高亮，推荐统一使用
- # 功能等效，但容易和 shell 脚本混淆，团队项目中建议避免
- 可以放在代码同行末尾，例如：
$status = $row['status']; // 来自 orders 表，0=待处理，1=已完成 - 不要在函数体中间密集写单行注释代替拆分——那说明函数该重构了
多行注释：说明“一段”而非“一行”
用 /* ... */ 描述一段代码的整体目的、算法思路、兼容原因或临时屏蔽逻辑。
- 适合写在函数上方，概括其职责与边界，例如：
/* 校验用户邮箱是否已注册且未被禁用，跳过管理员账号白名单 */ - 不能嵌套，
/* /* 内层 */ 外层 */会导致语法错误 - 不建议用它存作者、时间等元信息——这类内容更适合放进文件头的文档注释
- 临时屏蔽多行代码可用，但上线前应删除或转为 @todo 明确后续动作
PHPDoc 文档注释：给工具看的“说明书”
以 /** 开头、*/ 结尾的块注释，是 IDE、静态分析器和文档生成工具识别接口契约的基础。
立即学习“PHP免费学习笔记（深入）”；
- 必须严格以 /**（两个星号）起始，少一个 * 就变成普通注释，所有智能提示失效
- 第一行写简洁功能描述，空一行后再写标签，例如：
/** 计算订单最终应付金额，含税、运费与优惠叠加 */ - 关键标签要匹配实际签名：
@param int $orderId中的$orderId必须和函数定义参数名完全一致（大小写敏感） - 优先用小写原生类型：
string、int、array|null，不用String或Array
真正有用的注释，只回答“为什么”
代码已经说明“做了什么”，注释的任务是解释“为什么这么做”。重复语义的注释只会增加噪音。
- 避免：
$i++; // 给 i 加 1—— 这是代码本身就在说的事 - 推荐：
if ($retry > 3) return false; // 防止无限重试拖垮服务，按SLA设定上限 - 业务规则要写实：
// 折扣仅对实付满200元订单生效，不含运费与税费 - 配置项背后有依据：
'timeout' => 30, // 第三方支付网关平均响应2.3s，设10倍余量
