html注释是廉价却关键的文档基础设施，需写明“作用+上下文”，避免笼统标签名；ai常误判data-module、动态属性及条件渲染逻辑；上线前须检查todo/fixme、敏感信息和ssr/ssg注释失效风险。

HTML 注释本身不参与渲染，但它是自动化文档生成和长期可读性维护最廉价、最直接的基础设施——前提是注释写得对、位置准、内容有用。

为什么 <!-- --> 不能只写“header”或“nav”

这类注释在搜索时无法定位真实意图，也起不到文档作用。浏览器不会报错，但团队成员看到 <!-- header --> 时，根本不知道这个 <header></header> 是否包含 logo、是否支持 sticky、是否由 JS 动态注入。

• 真正有用的注释要说明「作用 + 上下文」，比如：<!-- Header: contains site logo, language switcher, and auth status bar; synced with header.js init() -->
• 避免在标签行内写注释（如 <div class="card"> <!-- product card -->），压缩工具可能删掉它，且破坏缩进一致性<li>注释必须配对出现：有 <code><!-- Main Content Start --> 就该有 <!-- Main Content End -->，否则搜索 End 会漏掉区块边界

AI 自动生成注释时最容易出错的三处

当前主流 AI 工具（如 InsCode、Cursor、GitHub Copilot）能识别 <nav></nav>、<footer></footer> 等语义标签并打上基础描述，但以下情况常误判：


Markdown to HTML
{"answer":"将 Markdown 转换为内嵌 CSS、样式精美的独立 HTML。完美适用于新闻简报、文档、报告及邮件模板。"}
下载
• data-module 值未被识别：比如 <section data-module="search-autocomplete"></section>，AI 可能忽略该属性，只写 <!-- section -->，而实际这个模块依赖 search.js 的 initAutocomplete()
• 动态属性未被解释：像 aria-hidden="true" 或 inert 这类可访问性控制，AI 很少主动说明“为何隐藏”，需人工补一句 <!-- hides icon from screen readers to avoid duplicate announcement -->
• 条件渲染逻辑缺失：模板中 <!-- IF user.isPremium --><div class="badge">PRO</div> <!-- ENDIF -->，AI 通常不注释条件本身，但这里恰恰需要说明权限判断依据和 fallback 行为

上线前必须检查的注释风险点

注释不是开发完成才加的装饰，而是上线流程里的一道校验关卡。

• 全局搜索 TODO 和 FIXME：确认所有标记都已处理或明确留痕；未解决的 FIXME 要带具体环境约束（如 <!-- FIXME: iOS Safari 17.5 breaks flex gap in carousel -->）
• 检查敏感信息：模板中若含 <!-- DEBUG: token=abc123 -->，构建后仍会出现在源码里，必须删或改用 data- 属性 + JS 控制
• 验证 SSR/SSG 行为：Next.js、Astro 等框架默认剥离 HTML 注释，本地开发看着正常，构建后注释消失——若逻辑依赖注释定位（如某些旧版构建脚本），就会失效

注释写得越早、越贴近真实上下文，后期维护成本就越低；但一旦开始靠猜“这段代码当初为什么这么写”，说明注释已经失职了。