<p>PHP单行注释推荐用//，#仅历史兼容且不推荐；多行注释必须用/ /且不可嵌套；文档注释须以/**开头才被工具识别，冗余注释影响OPcache性能。</p>
PHP单行注释用//还是#？
两者都合法，但//是主流且推荐写法。#虽被PHP解析为注释（兼容shell脚本习惯），但几乎没人用，IDE支持弱，团队协作时容易引发困惑。
常见错误现象：有人在配置文件或CLI脚本里混用#，结果迁移到Web环境后被误读为普通字符（比如出现在ini文件中），其实那不是PHP解析的——PHP只认//和/* */。
-
//可用于任意位置，包括语句末尾：$name = 'Alice'; // 设置用户名 -
#仅限于行首或空白后紧接，且不建议在函数体/类中出现 - PHP 8+ 对
#无特殊处理，它只是历史遗留兼容项，未来可能被弱化提示
PHP多行注释必须用/* */，不能嵌套
PHP不支持嵌套/* */，写两层会直接报错或截断逻辑。这是最容易踩的坑——尤其从JavaScript转过来的人，常下意识写成/* /* 内层 */ 外层 */，结果PHP只认第一个/*到第一个*/，后面代码直接裸奔。
使用场景：临时屏蔽一段代码、写较长说明、生成API文档前的草稿注释。
立即学习“PHP免费学习笔记（深入）”；
- 正确写法：
/* 这是一段多行注释，可以跨行，但不能包含 */ 字符 */ - 错误写法：
/* 外层 /* 内层 */ 结束外层 */→ PHP在第一个*/就终止注释，后续代码暴露 - 若真要“注释掉含
*/的代码”，改用//逐行注释，或用IDE快捷键批量加//
PHP文档注释（phpdoc）必须以/**开头，不是/*
只有/**（两个星号）开头的块注释才会被PHPDoc工具识别为文档注释。少一个*就是普通多行注释，IDE不会提取参数类型、不会补全方法签名、静态分析也跳过它。
常见错误现象：写成/* @param string $id */，结果PhpStorm不提示参数，PHPStan不校验类型，Laravel IDE Helper生成失败。
- 必须严格以
/**起始，结尾仍是*/，中间每行可选*对齐（非强制，但建议） -
@param、@return等标签必须独占一行，且@前不能有空格（* @param✅，* @param❌） - 函数参数名要和实际定义一致，大小写敏感；类型声明优先用PHP原生类型（
string、int），避免String（类名写法）
注释不是写小说，别让/**变成性能陷阱
文档注释本身不参与运行，但大量冗余注释会增大OPcache内存占用，尤其在微服务或容器化部署中，每个请求加载的文件多、注释体积大，冷启动慢一两百毫秒很常见。
性能影响常被忽略：PHP解析器需扫描全部/**块做语法树构建，哪怕没调用Reflection。这不是理论问题，真实压测中见过10万行注释拖慢23%的autoload时间。
- 删除已废弃函数的完整phpdoc，只留
// 已弃用，请用xxx() - 避免在循环体内写长注释（哪怕只是
//），编译阶段仍会解析整行 - CI流程中可用
php -l检查语法，但无法发现“注释过多”问题；需要额外用grep -r '/\*\*' | wc -l做基线监控
真正难的不是写注释，是判断哪句该删、哪句该留——尤其是别人写的、你不敢动的legacy代码里，那个看似无用的@deprecated可能正被CI里的某个检查脚本依赖着。
