PHP注释应严格区分用途：单行用//（非#），多行用/ /，文档块用/* /且仅用于函数/类等需PHPDoc解析处；注释核心是提升可读性与可维护性。
PHP 注释本身没有强制语法错误，但加错位置、混用风格、或遗漏关键信息，会让后续维护的人（包括几天后的你自己）抓狂。最稳妥的做法是：单行用 // 或 #，多行用 /* */，文档块用 /** */ —— 且仅在函数、类、常量前用。
单行注释该用 // 还是 #？
# 在 PHP 中确实合法，但几乎没人用。它源于 shell 脚本习惯，容易和配置文件混淆，IDE 支持也弱。主流项目（Laravel、Symfony、PHP-FIG PSR 标准）全部默认 //。
-
//是 PHP 官方文档首选，所有内置函数示例都用它 -
#在 CLI 脚本里偶尔出现，但一旦混进 Web 项目，会被 PHPCS（PHP CodeSniffer）直接报Squiz.Commenting.InlineComment.InvalidEndChar - 别为了“省一个字符”牺牲可读性 ——
// TODO: 检查用户权限比# TODO: 检查用户权限更易被编辑器高亮识别
/* */ 多行注释不能嵌套，但可以跨行写
PHP 不支持 /* /* 嵌套 */ */，会报 Parse error: syntax error, unexpected end of file。但它允许自然换行，只要不提前闭合。
/*
* 用户登录逻辑：
* - 验证邮箱格式
* - 查询数据库是否存在
* - 密码比对用 password_verify()
*/
if (filter_var($email, FILTER_VALIDATE_EMAIL)) { ... }
- 每行开头加
*是团队协作惯例，不是语法要求，但没它会被 PHPStan 或 PHP_CodeSniffer 的Squiz.Commenting.BlockComment规则警告 - 别把
/* */当成“临时屏蔽代码”的工具 —— 用if (false) { ... }或 IDE 的注释快捷键更安全，否则容易漏掉*/导致整段代码失效
什么时候必须用 /** */ 文档块？
只有当你写的函数、类、属性、常量需要被 PHPDoc 工具（如 phpDocumentor、PHPStorm、Psalm）解析时才用。它不是普通注释，是结构化元数据。
立即学习“PHP免费学习笔记（深入）”；
/**
* 根据用户 ID 返回完整用户信息
* @param int $id 用户唯一标识
* @return array|null 包含 name/email/created_at 的关联数组，不存在时返回 null
*/
function getUserById(int $id): ?array { ... }
-
/** */必须紧贴函数/类声明上方，中间不能有空行，否则 PHPStorm 不会自动补全参数提示 -
@param、@return等标签的类型要和实际一致（比如写@param string $id却传了int，Psalm 会报错） - 普通逻辑说明（比如“这里调用了第三方 API”）不要塞进
/** */，用//更轻量
最容易被忽略的是：注释不是写给机器看的，是写给下一个要改这段代码的人看的。如果一行 // 能说清，就别硬凑三行 /* */；如果函数行为复杂到需要类型和用途说明，那就老老实实写 /** */ 并保持字段对齐 —— 不为别的，就为下次 grep 时能快速定位。