PHP变量注释方法及规范详解

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 或 @var Product[]
• 避免模糊写法：@var mixed、@var object 会削弱类型检查价值

常量和配置变量：用 @const 或直接写注释说明用途

PHP 的 define() 和 const 声明不支持 PHPDoc，但类常量可以。文件级常量只能靠普通注释说明，而 IDE 无法识别。

• 类常量可加 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
• 混合类型（string|int）必须用联合类型语法（PHP 8.0+），而不是靠 @var 欺骗 IDE
• 第三方库返回值不确定时，@var 是必要补充，但应配合断言（assert(is_array($x))）增强健壮性

真正容易被忽略的是：局部变量永远无法被 PHPDoc 关联，哪怕你写得再规范。如果一个函数里有关键中间变量（比如 $normalizedData），靠注释不如拆成小函数，或用类型断言 + IDE 支持的 PHP 8 类型语法来保障可读性与可靠性。