PHP怎么注释常量_PHP常量注释格式【清晰】

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，是目前最稳的解法。