PHP数组注释只能写在数组声明前或后，用//或/ /说明用途和结构；不能在数组内部写行内注释，否则报语法错误；推荐用PHPDoc @var array{key: type}提升IDE支持。
PHP 数组注释该用什么语法
PHP 本身不支持在数组字面量内部直接写行内注释（比如 // 或 #），任何在 [...] 里加注释的写法都会导致解析错误。唯一合法且通用的方式是把注释写在数组声明**之前或之后**，用标准的 PHP 注释语法（//、/* */）说明整个数组的用途、结构或关键字段含义。
为什么不能在数组元素间写 // 注释
因为 PHP 解析器在处理数组字面量时，会把 // 后的内容当作代码的一部分尝试解析，而不是跳过——这会导致语法错误或意外截断。例如下面这段会报错：
$config = [
'host' => 'localhost', // 数据库主机
'port' => 3306, // 端口
];实际运行会提示 Parse error: syntax error, unexpected '/'。PHP 7.4+ 虽然支持尾随逗号，但**不支持尾随注释**。
推荐的注释位置和写法
把注释放在数组变量声明上方，用清晰的自然语言说明数组目的；对复杂结构（如多维、键名有业务含义），可配合 /* */ 块注释分段说明：
立即学习“PHP免费学习笔记（深入）”；
- 单行说明用
//，简洁明了 - 结构较复杂时用
/* */，可换行、标注字段语义 - 避免在
=>右侧加注释（不可靠，易被误读） - 如果数组用于函数参数或返回值，优先在函数文档块（
/** @return array */）中描述结构
// 用户权限映射表：key 为角色标识，value 为允许的操作列表
$permissions = [
'admin' => ['create', 'read', 'update', 'delete'],
'editor' => ['create', 'read', 'update'],
'viewer' => ['read'],
];
/*
- API 响应模板结构：
- 'code': 整数状态码（200/400/500）
- 'message': 提示文本
- 'data': 可选，具体业务数据
*/
$responseTemplate = [
'code' => 200,
'message' => 'success',
'data' => null,
];
IDE 和静态分析工具能识别的注释形式
如果你用 PHPStorm、VS Code（配合 intelephense）或 Psalm/PHPStan，可以在数组变量前加 PHPDoc 注释，帮助类型推导和自动补全：
/** * @var array{ * host: string, * port: int, * ssl: bool * } */ $databaseConfig = [ 'host' => '127.0.0.1', 'port' => 3306, 'ssl' => false, ];这种
@var array{...}语法不是 PHP 原生支持，但主流工具能解析并提供准确提示。注意字段名必须与实际键名完全一致（包括大小写和引号），否则类型检查会失效。最常被忽略的是：数组键名在 PHP 中默认是字符串，但 PHPDoc 的
array{key: type}里key不加引号——这是语法要求，加了反而无法识别。
- 'data': 可选，具体业务数据
*/
$responseTemplate = [
'code' => 200,
'message' => 'success',
'data' => null,
];
