真正可持续的做法是让HTML结构本身可读，注释仅补充非显性依赖和反直觉约束；应禁用描述性注释，改用语义化标签、data属性和机器校验的注释规范。
HTML 标签本身不承载业务语义，靠注释“自解释”反而会加剧维护负担——真正可持续的做法是让结构本身可读，注释只补关键上下文。
为什么 <!-- 用 div 包裹搜索框 --> 这类注释很快失效
这类注释的问题不在写法，而在它试图用静态文本描述动态行为：组件可能被复用、条件渲染、服务端注入，甚至被 JS 动态替换 DOM。一旦 div 被换成 section 或加了 data-search-container，注释就变成干扰信息。
- Git blame 里看到的往往是“更新注释”，而不是“修复逻辑”
- 新成员优先读注释而非结构，结果按过时描述理解 DOM 关系
- 格式化工具（如 Prettier）可能把注释挤到奇怪位置，破坏可读性
哪些注释值得保留：聚焦“非显性依赖”和“反直觉约束”
当 HTML 的行为无法从标签、属性、CSS 类或相邻代码中直接推断时，才需要注释。典型场景包括：
-
<!-- SSR 必须存在，否则 hydration 失败：nextjs hydration mismatch -->—— 指明服务端/客户端一致性硬约束 -
<!-- 依赖外部 JS 注入 contenteditable，勿删 tabindex -->—— 揭示隐藏的交互契约 -
<!-- 禁止嵌套 <form>：父表单提交时会触发两次 submit 事件 -->—— 记录浏览器兼容性陷阱
这类注释应紧贴对应标签，且必须包含具体后果（如 “hydration mismatch”、“两次 submit”），不能只写“注意”或“小心”。
立即学习“前端免费学习笔记（深入）”；
替代注释的更可靠手段：用语义化标记和约定代替解释
与其注释“这是搜索框”，不如让结构自己说话：
- 用
<search>替代<div class="search-wrapper">（配合现代浏览器支持检查） - 为关键区域添加
data-testid="header-search"或data-module="search-bar"，供测试和 JS 定位，而非人工阅读 - 在构建层统一处理：用 PostHTML 插件自动为含
role="search"的元素插入标准化注释（仅用于生成环境调试源码），避免手写
团队应约定：所有 data- 属性命名需与设计系统文档一致，比如 data-variant="compact" 对应 Figma 组件命名，而非开发随意造词。
团队落地时最容易忽略的一点
注释规范必须和 CI 流程绑定：用 ESLint + eslint-plugin-html 或自定义 PostHTML 规则，扫描出 <!--.*包裹.*-->、<!--.*div.*--> 这类模板化注释并报错；同时允许白名单正则（如 /SSR|hydration|tabindex|nested form/i）。没有机器校验的约定，三个月后就会退化成个人习惯。
