php常量注释必须用紧贴声明上方的/* / docblock，推荐封装为类常量并加@var标签；define()和全局const无法被工具识别，ide悬停和类型检查依赖此规范。
PHP 中常量本身不支持直接内联注释（比如 const FOO = 1; // 这个注释属于下一行），但可以通过文档块（DocBlock）在声明前添加结构化注释，这是唯一被 IDE、PHPStan、Psalm 和 PHPDocumentor 正确识别的方式。
PHP 常量的 DocBlock 注释必须写在 const 前一行
PHP 解析器不把常量当作“可文档化元素”处理，但 PSR-5（现为 PHPDoc 标准）明确允许为类常量添加 /** */ 块。IDE 和静态分析工具只认这种位置和格式：
/** * 表示用户处于激活状态 * @var int */ const STATUS_ACTIVE = 1;
如果写成这样，注释就失效了：
const STATUS_ACTIVE = 1; /** 错误：注释在声明后，不会被解析为该常量的文档 */
- 必须使用
/** */，不能用//或/* */ - 必须紧贴常量声明上方，中间不能有空行（部分工具如 PHPStan 允许 1 空行，但保守起见建议零空行）
-
@var标签推荐加上，尤其当类型不明显时（如字符串、布尔或自定义枚举值）
类常量和全局常量的注释方式不同
类常量可用完整 DocBlock；而 define() 或 const 在全局作用域声明的常量，无法被标准工具识别为文档目标——即使你写了 DocBlock，PHPStan 也不会把它关联到那个常量上。
立即学习“PHP免费学习笔记（深入）”；
- ✅ 推荐：全部使用
class封装常量，并用self::STATUS_XXX访问 - ❌ 避免：
define('API_TIMEOUT', 3000);—— 这种没有可靠注释机制，IDE 不提示，类型推导也弱 - ⚠️ 折中：
const API_TIMEOUT = 3000;在全局文件里，虽可加 DocBlock，但多数工具不索引它（PHPStorm 仅作普通注释高亮，不用于跳转或补全）
注释里怎么写类型和含义才清晰
光写“用户状态”不够，要说明取值范围、业务约束、是否可扩展。比如：
/** * 用户账户状态码 * - 0: 待验证邮箱 * - 1: 已激活 * - 2: 已冻结（管理员操作） * - 9: 已注销（不可逆） * @var int */ const STATUS_PENDING = 0; const STATUS_ACTIVE = 1; const STATUS_FROZEN = 2; const STATUS_DELETED = 9;
- 避免模糊描述如“正常状态”，改用“已通过邮箱验证且未被冻结”
- 若常量是位掩码（如
FILE_READ | FILE_WRITE），务必在注释中写出二进制或十六进制等价形式 - 对
true/false常量，注明默认行为倾向，例如：/** 启用调试日志输出（生产环境应设为 false） */
真正影响协作效率的不是“能不能加注释”，而是“加了别人能不能在 IDE 里悬停看到、能不能被静态检查捕获类型错误”。所以封装进 class + 正确位置的 DocBlock，是目前最稳的解法。
