php注释必须是标准phpdoc格式（/* /），含严格对齐的@param、@return等标签，类型与签名完全一致，且紧贴函数声明、项目已安装依赖，否则ide和静态分析工具无法识别。
PHP 注释不是写给人看的“说明书”，而是给 IDE 和静态分析工具吃的“饲料”——写错格式、漏标签、类型不匹配，phpstan 就报红，PhpStorm 就不提示参数，psalm 直接放弃推导。
PHP 函数必须用 /** 开头的 PHPDoc 注释
手写 // 或 /* */ 注释函数，等于没注释。IDE 无法关联参数名，intelephense 会把所有变量标成 mixed，phpstan 的 Parameter $x of function foo expects string, mixed given 错误就从这儿来。
- 必须以
/**开始（两个星号），*/结束，中间每行以*对齐 -
@param必须出现，类型 + 变量名 + 描述，且变量名要和函数签名**完全一致**（$userId≠$userid） -
@return不能省，哪怕返回void也得写@return void - 顺序固定：
@param→@return→@throws→@see，错序会导致 PHPStan 解析失败
/**
* 格式化用户昵称
*
* @param int $userId 用户唯一 ID，必须大于 0
* @param string|null $fallback 备用文本，为 null 时返回 '游客'
* @return string 格式化后的昵称（如「用户#123」）
* @throws InvalidArgumentException 当 $userId 小于 1 时抛出
*/
function formatUsername(int $userId, ?string $fallback = null): string {
@param 和 @return 类型必须反映真实运行时行为
注释类型不是“希望它是什么”，而是“它实际可能是什么”。写错类型会让调用方做无效断言，甚至掩盖 bug。
-
strpos()返回int|false，注释写@return int就是错的 - 配置读取函数文件不存在时返回
null，就得写@return array|null，不能假装“总会返回数组” - 数组结构明确时，用形状语法：
array{status: string, code: int}，比array强十倍 - 对象类型必须写完整命名空间：
@param \DateTimeInterface $date，不能简写成DateTimeInterface
单行和多行注释只用于临时说明或屏蔽代码
// 和 /* */ 不参与类型分析，纯人工阅读用途。滥用会导致 IDE 提示失效、静态检查失能。
-
//适合变量旁简短说明：$count = getActiveUsers(); // 排除已注销账号 -
/* */适合临时屏蔽整段逻辑，上线前必须清理，否则变成“幽灵注释” - 避免“废话注释”：
$i = 0; // 把 i 设为 0这类重复代码语义的内容 - 敏感信息（密钥、路径、内部 URL）绝不能出现在任何注释里，源码可被直接查看
IDE 不识别注释？先查这三个硬性条件
写了标准 PHPDoc 却没效果，90% 是卡在这三处，和注释内容无关：
- 函数声明前**不能有空行**——
/**必须紧贴function关键字上一行 -
@param中的变量名必须和函数签名大小写、下划线完全一致 - 项目根目录要有
composer.json，且已执行过composer install（IDE 依赖vendor/autoload.php加载类型信息）
最常被忽略的是最后一项：没有 vendor，再规范的 PHPDoc 也是摆设。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
