注释与模块化：如何写好HTML代码

本文深入探讨了如何通过合理使用HTML注释与科学的模块化策略来构建真正可维护的HTML代码：强调注释不是装饰而是协作命脉，主张组件级、语义明确、位置规范的注释实践，同时警惕行内注释和动态HTML中的注释失效风险；在模块化方面，倡导以`data-module`等自定义属性替代class进行职责解耦，结合构建工具链选择适配场景的片段复用方案（如服务端包含或静态构建），并一再提醒——再精妙的注释与模块化也无法弥补糟糕的DOM结构，唯有坚持语义化标签、克制嵌套、兼顾无障碍，才能从根源上提升代码的长期可读性、可调试性与可重构性。

HTML 注释不是可有可无的装饰

HTML 注释在多人协作或半年后回看代码时，直接决定你愿不愿意重写一遍。它不参与渲染，但影响可读性、调试效率和重构信心。

常见错误是只写 这类模糊注释，或者把整块结构塞进一个长注释里，结果改一处，注释全失效。

• 组件级注释建议放在
  或

  开头，用明确作用+上下文说明，比如：
• 避免在行内写注释（如
  ），容易被压缩工具误删，也破坏标签结构清晰度
• 动态生成的 HTML（如模板引擎输出）慎用注释——某些 SSR 框架（如 Next.js 的 getStaticProps）会剥离注释，导致本地开发和构建后行为不一致

用 data-module 替代 class 做模块标识

靠 class="header-nav" 或 id="main-slider" 定位模块，在 CSS 和 JS 里耦合太紧。一旦改样式类名或加新交互，JS 很可能静默失效。

更可靠的做法是用语义化自定义属性做模块锚点：

<nav data-module="navigation" data-config='{"sticky": true, "mobileBreakpoint": 768}'>
  <ul>...</ul>
</nav>

• data-module 值应为小写短横线分隔（如 product-carousel），避免空格或大写字母，方便 JS 用 document.querySelectorAll('[data-module="product-carousel"]') 精准选取
• 配置信息尽量走 data-config 并 JSON 化，而不是多个 data- 属性拼凑（如 data-sticky="true" data-breakpoint="768"），后者难维护且易类型错乱
• 不要把 data-module 当成“给 JS 用的 class”，它不该出现在 CSS 选择器里（如 [data-module="header"]），否则样式逻辑和模块职责就混了

拆分 HTML 不等于盲目切文件

所谓“模块化 HTML”，不是把每个