PHP类属性和方法的标准注释必须用/* /紧贴声明上方，属性需@var标注类型，方法需@param、@return及@throws；@var与原生类型声明须一致，函数体内禁用PHPDoc格式。
PHP 类属性和方法怎么写标准注释
PHP 本身不解析文档注释（docblock）来影响运行逻辑，但 IDE、PHPStan、Psalm、PHPDocumentor 等工具依赖 /** */ 风格的注释提取类型、描述与约束。正确写法直接决定自动补全准不准、静态分析报不报错、生成文档全不全。
关键不是“能不能写”，而是“写在哪”“写什么格式”“哪些标签必须有”。下面以最常用场景为准：
-
/**必须紧贴在类、属性、方法上方，中间不能空行 - 属性注释必须包含
@var，明确标注类型（如@var string|null） - 方法注释必须包含
@param（每个参数一行）、@return，有异常要加@throws - 类型建议用 PHP 8+ 原生类型（
string、int、array），复杂结构用array或list
/**
* 用户登录会话管理器
*/
class SessionManager
{
/**
* 当前用户 ID，未登录时为 null
* @var int|null
*/
private $userId;
/**
* 初始化会话并绑定用户
* @param int $userId 用户唯一标识
* @param string $token 会话令牌
* @return bool 是否成功启动
* @throws InvalidArgumentException 当 token 格式非法时
*/
public function start(int $userId, string $token): bool
{
// ...
}
}
PHPDoc 注释里 @var 和 PHP 7.4+ 属性类型声明冲突吗
不冲突，但必须保持一致——否则静态分析工具会报错，IDE 补全也会出问题。PHP 7.4 引入的属性类型声明（如 private string $name;）是运行时强制校验，而 @var 是给工具看的“提示”。两者类型不一致时，PHPStan 默认以 @var 为准，但会警告你“type mismatch”。
立即学习“PHP免费学习笔记（深入）”；
- 如果用了原生类型声明（PHP 7.4+），
@var可省略，但建议保留——尤其当需要表达更细粒度语义时（如@var list而非仅array） - 如果属性是
private array $data;，但实际只存['id' => 1, 'name' => 'foo']，推荐写成@var array{ id: int, name: string }（PHPStan 支持的数组形状语法） - 可空类型注意：原生写
private ?string $desc;，对应@var string|null，不能只写@var string
PHP 函数内联注释用 // 还是 /** */
函数内部逻辑块用 // 或 /* */ 即可，无需强求 PHPDoc 格式；只有函数/方法签名上方才必须用 /** */ + 标准标签。混淆这两者会导致 PHPDocumentor 无法提取 API 文档，也浪费 IDE 解析资源。
- 函数体内的说明性文字：用
//开头，简洁说明“为什么这么做”，不是“做什么”（后者应由代码自解释） - 临时禁用某段逻辑：可用
/* ... */包裹，但上线前必须清理 - 禁止在函数体内写
/** @var User $user */这类伪 PHPDoc——PHPStan / Psalm 不识别，且易过期；应改用断言或类型转换（如$user = $this->getUser() ?? throw new LogicException(...);）
public function processOrder(int $orderId): void
{
// 获取订单前先校验状态，避免并发修改导致数据不一致
$order = $this->orderRepo->find($orderId);
if ($order->isPaid()) {
return;
}
$this->paymentService->charge($order);
}
PHP 注释被 IDE 忽略或不显示补全？检查这三点
不是注释没写对，就是环境没配对。常见断点就三个位置：
- IDE 是否启用 PHPDoc 解析：PhpStorm 默认开启，但需确认 Settings → Languages & Frameworks → PHP → PHPDoc 中 “Enable PHPDoc support” 已勾选
- 项目是否被识别为 PHP 项目：右键项目根目录 → Mark Directory as → Sources Root，否则注释解析器不工作
- Composer autoload 配置是否完整：如果类在
src/下但composer.json没配"autoload": {"psr-4": {"App//": "src/"}}，IDE 可能找不到类定义，自然不读注释
注释不是装饰，是契约。写错一行 @var，可能让后续十个人花两小时排查类型错误。越早统一规范，后期维护成本越低。