html注释需严格遵循闭合规则，以“”结束，中间含独立“--”或嵌套会导致提前截断或代码消失，且不可出现在标签属性值内。
HTML 注释本身没有语法错误风险，但写错位置、嵌套或含敏感信息，会直接暴露给用户、破坏结构、干扰自动化工具——它不是“随便写写就完事”的辅助手段，而是协作链路上的关键节点。
注释语法必须严格遵循 <!-- 和 --> 闭合规则
浏览器解析 HTML 时，遇到 <!-- 就进入注释状态，直到下一个 -->（注意：必须是连续两个短横）才结束。中间内容完全不渲染，也不参与 DOM 构建。
常见错误包括：
-
<!-- 这里不能出现 -- -->：中间有独立的--会导致提前截断，后续代码可能被意外注释或解析出错 -
<!-- <!-- 嵌套注释 --> -->：HTML 不支持嵌套注释，外层<!--会一直匹配到第一个-->，导致后面一大段代码“消失” - 在标签属性值里写注释，比如
<div class="<!-- temp -->header">：这是非法语法，会触发 HTML 解析器报错或静默失败<p>正确写法只有一种：<code><!-- 描述性文字 -->，且必须独占一行或夹在合法标签边界之间。团队协作中注释要能被机器识别和人工快速定位
光写“这里改过”没用，关键是谁改的、为什么改、是否已确认。协作注释不是日记，是轻量级工单。
建议统一使用以下格式：
- 待办事项：
<!-- @todo 张三 2026-07-15: 替换为 useHeader hook，当前硬编码样式 --> - 审查反馈：
<!-- @review 李四 2026-06-10: data-user-id 应校验非空，否则 SSR 渲染异常 --> - 数据来源说明：
<div data-api-key="abc123"> <!-- 后端注入，禁止前端修改 --><li>文件头部必须含 author 和 modified：<code><!-- author: 王五; modified: 2026-06-11 --> -
不存敏感信息：API 密钥、内部路径、测试账号等绝不能出现在
<!--里——源码可被任何人右键查看 - 不解释显而易见的内容：
<!-- 按钮 --><button>提交</button>这类注释纯属噪音，反而稀释关键信息密度 -
不长期保留调试痕迹：
<!-- DEBUG: console.log(user) -->必须在上线前清理，否则影响加载性能（虽小但累积）且暴露内部逻辑 - 模块级注释放在
<section></section>或<article></article>开头前一行，且上下各空一行 - 关键
data-属性旁紧贴注释，不要隔开标签或换行，例如：<div data-interval="5000"> <!-- 后端配置，单位毫秒 --><li>响应式断点相关块前加注释+空行：<code><!-- mobile-only section --><br><div class="mobile-nav"> <li>避免把注释塞进一行标签末尾：<code><header class="main"><!-- 主页头部 --></header>—— 这种写法 IDE 难以高亮，也破坏可读性
这些格式能被 VS Code 的 TODO Highlight 插件识别，也能被自定义 ESLint 规则（如
eslint-plugin-html）扫描并告警未处理的@todo。注释内容必须避开三个高危区
看似无害的注释，可能成为安全或维护隐患：
尤其注意：某些构建工具（如 Webpack + html-webpack-plugin）默认不剥离注释，生产环境照样可见。
空行与注释位置决定协作效率上限
注释不是贴在代码旁边就行，它得嵌入逻辑分界点，才能真正降低理解成本。
实操建议：
最常被忽略的是：注释位置一旦松散，就失去“视觉锚点”作用；而一个没对齐的空行，比没写注释更误导人。
- 待办事项：
