模板注释是重构中判断意图与历史上下文的关键线索，但也可能掩盖问题；需验证其真实性、清理过期内容、规范书写并警惕注释与代码不一致。
模板注释本身不参与运行，但在遗留代码重构中，它常成为判断“作者意图”和“历史上下文”的线索，也可能是掩盖问题的盲区。处理得当能辅助理解；忽略或滥用则可能拖慢重构节奏。
识别注释是否反映真实逻辑
很多老模板里存在类似 {/* 旧版兼容，暂不删除 */} 或 {// 这里有问题，但先留着 } 的注释。这类内容需结合实际渲染结果验证：
- 打开对应页面，检查该区域是否仍在生效、是否被 JS 动态覆盖、是否已被新逻辑绕过
- 搜索该注释关键词在整个项目中的出现次数，确认是否全局失效
- 若注释指向已废弃的变量（如
{$old_user_info}）且模板中无定义，说明该段可安全移除
清理无效注释，避免干扰重构判断
ThinkPHP 模板注释在编译后自动清除，但源码中堆积大量过期注释会降低可读性，尤其在多人协作重构时易引发误解：
- 删除明确标记为“临时”“待删”“测试用”且超过三个月未更新的注释
- 合并相邻多行注释为单行，减少视觉噪音，例如将三行说明压缩为
{/* 用户头像尺寸：宽80px，圆角50%，需适配Retina */} - 禁用 IDE 自动补全模板注释功能，防止新模板中无意义地插入空注释
用注释标注重构痕迹，而非掩盖问题
重构过程中应把注释当作轻量级协作记录，而非替代方案：
立即学习“PHP免费学习笔记（深入）”；
- 在修改过的区块上方添加简短注释，如
{/* @refactor 2026-06 由 layout.html 统一管理头部 */} - 对暂时保留但计划替换的逻辑，写明后续动作：
{/* TODO: 替换为 PermissionService::can() 校验，见 #issue-142 */} - 避免使用模糊表述如“优化中”“可能有问题”，必须包含时间、责任人或追踪依据
警惕注释与实际行为不一致的风险
有些注释声称“已启用布局”，但配置中 layout_on 为 false；或写着“支持多语言”，却没调用 lang() 方法。这类不一致是典型坏味道：
- 运行一次模板编译命令
php think clear:template，再比对生成的缓存文件，确认注释描述与实际输出是否匹配 - 对含条件判断的注释（如
{// 当 $type == 'admin' 时显示按钮}），在模板中补上对应逻辑或删掉注释 - 把反复出现的“注释说一套、代码做一套”情况汇总，作为团队规范修订依据
