PHP方法注释必须用/开头的PHPDoc格式，否则IDE不识别参数、静态分析工具跳过检查、文档生成失败；/*和//因不进入反射系统而无效，且/须紧贴函数声明无空行，类型声明须准确匹配签名并反映真实运行可能值。
PHP方法注释必须用/**开头的PHPDoc格式，否则IDE不识别参数、静态分析工具（如PHPStan）跳过检查、生成文档失败——这不是建议，是硬性前提。
为什么/*和//不能替代/**
普通块注释/*或单行注释//只是被PHP解析器忽略，不会进入反射系统。IDE（如PhpStorm、VS Code + intelephense）只扫描以/**起始、紧贴函数声明上方且中间无空行的注释块，提取@param、@return等标签。
常见错误现象：
- 写了
/* @param string $id */，但IDE不提示参数类型，调用时仍报Undefined variable $id - 函数上方隔了一行空行，
/**就失效——PHPDoc必须“紧贴”函数声明 - 用
/*（一个星号）代替/**（两个星号），phpdoc工具直接跳过整块
@param和@return怎么写才不误导人
类型声明不是凑数，它直接影响调用方的类型推导和安全判断。写错比不写更危险。
立即学习“PHP免费学习笔记（深入）”；
-
@param变量名必须和函数签名完全一致，包括大小写：$userId≠$UserID - 类型优先用PHP 8+原生语法：
string|null✅，String❌（会被当成类名）、array of string❌ - 返回数组结构明确时，用数组形状：
@return array{code: int, message: string, data?: array}，别只写array - 函数可能返回
false（如fopen()、strpos()），就必须写@return int|false，不能假装“总是成功”
哪些地方容易被忽略但实际影响大
很多团队只关注“有没有注释”，却踩在几个隐蔽但后果严重的点上：
- 项目没运行
composer install，vendor/autoload.php未加载 → IDE无法解析命名空间类型（如@param \DateTimeInterface $date） - 大量废弃函数还留着完整PHPDoc → 增大OPcache内存占用，实测冷启动慢200ms+
- 在
@param里写string $name 用户姓名，但业务要求是“中文2–10字符”，这种约束string类型声明表达不了，得靠注释补全 - 构造函数参数有默认值为
null，类型声明写string|null，但注释里没说明“传null表示使用系统默认用户名”，调用方就只能猜
真正难的不是语法，是每次写@param时多问一句：这个变量在真实运行中到底可能是什么？而不是你希望它是什么。
