<p>ThinkPHP注释分三类：模板层用{/ /}且禁用HTML注释；接口文档需专用标签如@api并严格位置与格式；PHP代码用标准PHPDoc但须匹配框架特性；所有注释须真实、简洁、可追踪。</p>
ThinkPHP 代码注释不是可有可无的装饰，而是影响重构效率、接口联调、团队协作和长期维护的关键环节。它分三类场景：模板层注释、控制器/模型层 PHPDoc 注释、以及路由或接口文档所需的专用标签注释——每类规则不同，混用就会失效。
模板注释：仅用于视图理解，不参与运行
ThinkPHP 模板（.html 文件）中使用 {/* 注释内容 */} 或 {// 注释内容 }，注意：
• { 和注释标记之间不能有空格，{ /* 错误 */} 会导致解析失败
• HTML 标准注释 <!-- --> 在模板中无效，可能报错或暴露到前端
• 模板注释在编译后自动清除，不进缓存，也不被 PHP 静态分析工具识别
• 重构时重点验证其真实性：若注释写“旧版兼容”，但对应变量（如 {$old_user_info}）未定义或页面已无渲染效果，应直接删除
接口文档注释：必须用专用标签，且位置严格
生成 Swagger 或 think-apidoc 文档，靠的是 @api（think-swagger）或 @ApiParams（think-apidoc）这类非标准 PHPDoc 标签：
• @api {POST} /api/user 必须紧贴方法上方，与 @apiParam 之间不能有空行
• @apiParam {string} username 用户名 中类型必须小写（string，不是 String）
• 嵌套字段如 data.profile.name 要扁平化为 data_profile_name 单独声明
• 路由必须显式绑定（如 Route::post('api/user', 'api.UserController/create')），Route::resource() 自动推断的路径不会被扫描到
PHP 代码注释：按用途区分，避免信息污染
控制器、模型、服务类等 PHP 文件，仍用标准 PHPDoc，但需配合框架特性：
• 方法级注释建议包含 @param、@return，尤其对传入模板的数据加 @var 类型提示（如 @var string $title），便于 IDE 和 PHPStan 校验
• 关联方法（如 hasMany()）的参数注释曾存在歧义，以官方文档为准：第三个参数是当前模型主键，不是关联模型主键
• 数据库字段注释不在 Db::getFields() 返回结果里，需手动查 information_schema.columns 表获取 column_comment，并注意 MySQL 版本、字符集和云数据库权限限制
立即学习“PHP免费学习笔记（深入）”；
注释管理原则：真实、简洁、可追踪
注释不是历史存档，而是轻量协作记录：
• 删除所有标记为“临时”“待删”“测试用”且超三个月未更新的内容
• 重构时添加带时间戳的标记，如 {/* @refactor 2026-08 由 layout.html 统一管理头部 */}
• 避免模糊表述，如“此处有问题”“后续优化”，必须写明动作、依据或关联 issue 编号
• 发现“注释说一套、代码做一套”的情况（如注释写“已启用多语言”，却没调用 lang()），应汇总为团队规范修订输入
