<p>PHP注释是团队协作与维护的关键，单行注释（//或#）应仅用于意图不清处，多行注释（/ /）适合说明函数目的与边界，PHPDoc（/* /）需规范标注@param、@return等以形成接口契约，注释重在解释“为什么”而非“怎么做”。</p>
PHP注释不是可有可无的装饰，而是团队协作、后期维护和自我复盘的关键线索。写得清楚，别人（包括未来的你）才能快速理解逻辑；写得随意，反而比不写更误导人。
单行注释：用//或#，别在关键逻辑旁“画蛇添足”
PHP支持//和#两种单行注释方式，功能完全一致。重点在于“何时该用”——只解释**意图不清、反直觉或临时绕过的逻辑**，而不是每行都加。
- ✅ 好例子：// 用户状态为-1时代表已软删除，跳过计费校验
- ❌ 坏例子：// $i++ // 自增i（代码本身已足够清晰）
- ⚠️ 注意：别把调试用的// echo $data;留在生产代码里，提交前务必清理
多行注释：/* */适合说明函数目的、参数规则和边界条件
当一段逻辑涉及多个变量协同、存在特殊输入限制，或封装了业务规则时，用/* ... */集中说明比零散的单行注释更有效。
- ✅ 推荐写法：在函数上方用多行注释说明“做什么、为什么这么做、谁会调用、哪些参数不能为null”
- ❌ 避免嵌套：PHP不支持/* /* 内层注释 */ 外层注释 */，会导致语法错误
- ? 小技巧：IDE（如PhpStorm）能自动识别/**开头的多行注释并生成文档结构，建议优先用/**而非/*
文档块注释（PHPDoc）：不只是给工具看，更是给同事看的契约
/** ... */格式的PHPDoc不是摆设。它被IDE用于自动补全、被静态分析工具（如PHPStan）用于类型校验、也被团队当作接口说明书。
立即学习“PHP免费学习笔记（深入）”；
- @param 必须写明类型和含义，例如 @param int $timeout 超时秒数，最小值为1
- @return 别只写@return array，要说明数组结构：@return array{user_id: int, name: string, is_active: bool}
- @throws 标明可能抛出的异常及触发场景，比如@throws InvalidArgumentException 当email格式不合法时
注释≠解释代码，而是填补“为什么”的空白
代码讲的是“怎么做”，注释要回答“为什么这么做”。一个没有注释的函数如果逻辑清晰、命名准确，往往比一堆解释变量赋值的注释更易读。
- 关注“异常路径”：比如// 此处不抛异常，因上游已保证$amount > 0
- 记录决策依据：// 使用BCMath而非float，避免金额计算精度丢失
- 标记待办：// TODO: 后续对接风控系统，此处需增加token校验（但记得定期清理过期TODO）
