必须用phpdoc（/**开头），否则ide无法识别类型、跳转失效，phpstan/psalm静态分析基本失效；需严格遵循语法规范与项目配置要求。
PHP 函数注释该用 PHPDoc 还是随便写两行？
必须用 PHPDoc（即以 /** 开头的块注释），否则 IDE 无法识别参数类型、无法跳转到定义、phpstan 和 psalm 也基本失效。手写 // 或 /* */ 注释，等于没写。
常见错误现象：PHPStorm 不提示参数、vscode 的 intelephense 报 Undefined variable $xxx、类型推导全成 mixed。
-
@param必须写，类型 + 变量名 + 描述，类型要用 PHP 8+ 原生语法（如string|null，别写String或array of string） -
@return必须写，void 不能省略；返回数组要写清结构，比如array{status: string, code: int} - 不写
@throws不代表没异常，但一旦函数明确 throwInvalidArgumentException，就得标出来，否则调用方无法静态检查
参数类型写 string 还是 string|false？
取决于函数真实行为——不是“理想情况”，而是“实际可能返回什么”。比如 strpos() 返回 int|false，注释写成 @return int 就是错的，会误导调用方做无效的类型断言。
使用场景：你封装了一个读配置的函数，文件不存在时返回 null，那注释里就得写 @return array|null，而不是假装它“总会返回数组”。
立即学习“PHP免费学习笔记（深入）”；
- 优先用联合类型（
string|int），不用mixed除非真不确定 - 数组键名结构明确时，用数组形状（
array{name: string, age: int}），比array强十倍 - 对象类型写完整命名空间，如
@param \DateTimeInterface $date，别简写成DateTimeInterface
IDE 不识别注释？检查这三处硬性条件
写了 PHPDoc 却没效果，大概率卡在这几个地方，和注释内容无关。
- 函数声明前必须紧贴，中间不能有空行（
function foo() {}上面隔了一行空行，IDE 就断开关联） -
@param的变量名必须和函数签名完全一致，包括大小写（$UserID≠$userid） - 项目根目录要有
composer.json，且已运行composer install—— 很多 IDE 依赖vendor/autoload.php加载类型信息
PHP 8.0+ 属性和构造函数参数注释能省吗？
能省，但不建议。属性类型声明（public string $name;）和构造器参数类型（public function __construct(private int $id)）已经提供基础信息，@var 和 @param 看似冗余，但仍有不可替代的作用：
- 描述字段业务含义（
@var string 用户手机号，需带区号），类型声明做不到这点 - 标注非常规约束（
@var non-empty-string，虽然 PHP 还不原生支持，但psalm能识别） - 构造器参数若含默认值为
null，类型声明写string|null，但注释可补充“仅用于测试 mock”这类上下文
复杂点在于：类型声明和 PHPDoc 类型不一致时，工具会以 PHPDoc 为准（phpstan 默认如此），所以别让两者打架。一个容易被忽略的地方：如果用了 #[\SensitiveParameter] 这类 PHP 8.2+ 属性，注释里也得同步说明敏感原因，光靠属性名没人看得懂。
