HTML注释是影响定位效率、协作成本和重构风险的关键信号系统；未闭合或含--会破坏解析，模块标记不配对降低可维护性，TODO未清理暴露隐患，需统一规范并随代码同步更新。
HTML 注释在大型项目里不是“可有可无的装饰”，而是直接影响定位效率、协作成本和重构风险的关键信号系统——写得不对，比不写还危险。
注释未闭合或含 -- 会导致页面结构崩坏
浏览器解析 HTML 时，遇到 <!-- 就开始跳过内容，直到匹配到第一个完整的 -->。如果注释里意外出现 --（比如写成 <!-- 这里是--临时方案 -->），解析器会在第一个 -- 处提前终止注释，后续所有 HTML 都可能被当作注释忽略。
- 常见错误现象：
<div>正常内容</div>突然不渲染，检查 DOM 发现它被“吞掉”了 - 调试方法：用浏览器开发者工具的“Elements”面板查看实际解析出的 DOM 树，而非源码视图
- 规避方式：禁用编辑器自动补全
-->的习惯；人工输入时避开连字符组合；CI 流程中可用 ESLint 插件eslint-plugin-html检测非法字符
模块起止标记不配对会破坏代码定位能力
大型项目靠注释快速跳转区块，但若只有 <!-- Header Start --> 却漏掉 <!-- Header End -->，或嵌套层级错位，就会让“Ctrl+F 查找区块”失效，反而增加理解成本。
- 使用场景：多人并行开发同一 HTML 文件，或接手遗留项目时快速厘清结构
- 实操建议：统一采用“Start/End”配对格式，避免用“Begin/Finish”等不一致词；用 IDE 的代码折叠功能验证是否能正确收起整个区块
- 参数差异：某些团队用
==包裹主区域（如<!-- == HEADER == -->），用-包裹子模块（如<!-- - Logo - -->），关键在于全项目统一，而非符号本身
TODO/FIXME 注释没清理会变成线上隐患
开发阶段留下的 <!-- TODO: 后续接入权限校验 --> 或 <!-- FIXME: Safari 下 margin 不生效 --> ，上线后仍留在生产环境，不仅暴露实现细节，更可能被爬虫抓取、被竞品分析，甚至误导运维排查方向。
立即学习“前端免费学习笔记（深入）”；
- 性能影响：单个注释体积小，但千行注释累计增加 KB 级传输量，对首屏加载有可测量拖累
- 构建处理：Webpack 中可用
html-webpack-plugin配置minify.removeComments: true；Vite 项目推荐用vite-plugin-html的inject: { data: {} }+ 自定义过滤逻辑 - 容易踩的坑：误删版权注释（如
<!-- © 2026 MyCorp. All rights reserved. -->）；或把条件注释（<!--[if IE]>）当普通注释一并移除，导致旧版兼容逻辑丢失
注释解释“为什么”比描述“是什么”更重要
写 <!-- 导航栏 --> 是无效注释，因为 <nav></nav> 标签本身已说明用途；而 <!-- 为适配 iOS 15.4+ Safari 的 scroll-behavior: smooth 兼容性降级 --> 才真正降低后续维护的认知负荷。
- 典型高价值注释类型：可访问性处理依据（如
<!-- aria-hidden="true" 因图标已有文本替代，避免屏幕阅读器重复播报 -->）、动态属性来源（如<!-- class 绑定来自 Vue 的 isMobile 计算属性，非静态值 -->）、临时 hack 原因（如<!-- 强制触发重绘修复 Chrome 119 下 transform 动画卡顿 -->） - 语言选择：团队若含国际化成员，注释优先用英文，哪怕项目中文为主；避免中英混杂（如
<!-- 修复IE11 bug -->）造成搜索和理解断层 - 版本控制提示：在文件顶部加变更注释（如
<!-- v2.3.1 - 2026-06-15: 重构 footer 为 Web Component，移除 jQuery 依赖 -->），但需配套 Git 提交信息，不可替代 commit message
注释的生命力不在数量，而在是否随代码同步演进。一个被遗忘的 <!-- 这里将来要改成 SSR --> 注释，比完全没注释更危险——它制造虚假确定性，让人误以为“这事有人管”。
