PHP注释需规范使用：单行注释统一用//，禁用#；PHPDoc须完整包含@return和@throws；调试代码不可藏于注释块；注释应解释“为什么”而非“怎么做”，并随业务规则同步更新。
PHP注释本身很简单，但用错地方、写错格式、忽略维护，反而会拖慢开发节奏、误导协作者，甚至引发安全隐患。真正影响效率的不是“要不要写”，而是“怎么写才有效”。
单行注释混用//和#，却不知道它们有作用域差异
// 和 # 在PHP中确实都能实现单行注释，但很多人没注意：在heredoc或nowdoc语法块内，# 不会被识别为注释符，而// 仍可能被误解析（尤其嵌套时）。更关键的是，团队统一风格能减少协作歧义——PSR-12 明确推荐优先使用//，# 仅限shell脚本兼容场景。
- 避免在字符串或动态代码块里用
#做注释 - 函数内逻辑分段建议用
//，而非混合使用 - IDE自动补全通常只识别
//触发的注释提示
文档注释（PHPDoc）只写@param，漏掉@return和@throws
很多开发者以为加了@param就算完成PHPDoc，结果类型提示失效、IDE无法推导返回值、异常流不可追溯。PHPStan、Psalm等静态分析工具严重依赖完整PHPDoc，缺一项就可能跳过关键校验。
- 凡有明确返回值的函数，必须写
@return（含void或mixed） - 调用外部服务、文件操作、数据库查询等潜在抛出异常的，补上
@throws - 用
@deprecated标记废弃接口，比口头约定更可靠
把调试用的die()、var_dump()留在注释区，当成“临时备注”
这类“伪注释”最危险：看着像注释，实则隐藏可执行代码。上线前容易遗漏清理，轻则输出敏感数据，重则中断流程。更隐蔽的问题是，Git diff里它们常被忽略，导致问题潜伏数月。
立即学习“PHP免费学习笔记（深入）”；
-
/* debug: var_dump($data); */不等于注释，是待删除代码 - 调试信息应统一走
error_log()+ 开发环境开关，而非注释块 - 用IDE的“TODO”或“FIXME”标记代替随意写死的调试语句
注释描述“怎么做”，而不是“为什么这么做”
“循环遍历数组”“调用API获取数据”这类注释毫无价值——代码本身已说明行为。真正需要注释的是决策依据：为什么选这个算法？为什么这里要绕过缓存？为什么必须用floatval()而不是(float)？这些上下文一旦丢失，后续维护成本倍增。
- 优先解释意图、约束条件、历史原因（如“因支付网关v2.1不支持空字符串，此处强制转空格”）
- 避免重复代码字面意思，比如
// 增加用户积分不如// 积分按订单金额1:1兑换，不含运费（见财务协议第3.2条） - 业务规则变更时，同步更新对应注释，而非只改代码
