PHP变量不支持内联注释，需在声明前用DocBlock注释，类属性支持@var等标签说明类型与用途，局部变量无法被PHPDoc关联，应优先使用PHP 7.4+属性类型声明。
PHP 变量本身不支持内联注释语法（比如 // $a = 1; // 这不是变量注释），所谓“变量注释”，实际是指在变量声明前用文档块（DocBlock）说明其用途、类型、作用域等，主要服务于 IDE 提示、静态分析（如 PHPStan/ Psalm）和生成 API 文档（如 phpDocumentor）。
PHPDoc 注释变量：必须写在变量声明前一行
PHP 不允许在 var、public、private 等关键字后直接加 DocBlock；必须把注释放在变量声明语句的正上方，且紧邻（中间不能有空行）。
- 类属性（property）支持完整 PHPDoc，包括
@var、@deprecated、@since等 - 函数/方法内局部变量不被 PHPDoc 规范支持，IDE 和分析工具通常忽略它们的上方注释
- 全局变量（
$GLOBALS或文件级$foo）无法被标准 PHPDoc 关联，不建议注释
/** * 用户登录态令牌，JWT 格式，有效期 2 小时 * @var string */ private $authToken;
@var 标签是核心：类型必须准确，否则误导 IDE
@var 是变量注释中唯一强制推荐的标签。它直接影响 PhpStorm、VS Code + intelephense 的类型推导和自动补全——如果写错，补全会失效或报假错。
- 基础类型用小写：
@var int、@var bool、@var array - 对象类型写完整类名：
@var User、@var \DateTime（带命名空间时必须反斜杠开头） - 联合类型用
|分隔：@var string|int|null（PHP 8.0+ 原生类型支持后更常用） - 数组要明确键值类型：
@var array<string, Product>或@var Product[] - 避免模糊写法：
@var mixed、@var object会削弱类型检查价值
常量和配置变量：用 @const 或直接写注释说明用途
PHP 的 define() 和 const 声明不支持 PHPDoc，但类常量可以。文件级常量只能靠普通注释说明，而 IDE 无法识别。
立即学习“PHP免费学习笔记（深入）”；
- 类常量可加 PHPDoc，但只支持
@var（实际应为@const，但多数工具仍认@var） - 配置变量（如
$config['db']['host']）建议在 config 文件顶部统一说明结构，而非逐个注释 -
环境变量（
$_ENV）不在代码中声明，注释应写在 .env 示例文件或部署文档里
/** * 数据库连接超时秒数 * @var int */ public const DB_TIMEOUT = 30;
别依赖注释替代类型声明：PHP 7.4+ 属性类型更可靠
PHP 7.4 引入了属性类型（property type declarations），它比 @var 更严格、运行时生效，且 IDE 和静态分析器优先信任它。
- 有原生类型就不用
@var：例如private string $name;不需要再写@var string -
@var仅用于补充原生类型无法表达的情况：如array<int, array{status: string, code: int}> - 混合类型（
string|int）必须用联合类型语法（PHP 8.0+），而不是靠@var欺骗 IDE - 第三方库返回值不确定时，
@var是必要补充，但应配合断言（assert(is_array($x))）增强健壮性
真正容易被忽略的是：局部变量永远无法被 PHPDoc 关联，哪怕你写得再规范。如果一个函数里有关键中间变量（比如 $normalizedData），靠注释不如拆成小函数，或用类型断言 + IDE 支持的 PHP 8 类型语法来保障可读性与可靠性。
