HTML注释是提升可读性、调试效率与重构信心的关键工具，不参与渲染但直接影响协作与维护质量；应避免模糊注释和行内注释，推荐组件级明确说明，慎用于动态HTML，并以语义化结构为根本前提。
HTML 注释不是可有可无的装饰
HTML 注释在多人协作或半年后回看代码时，直接决定你愿不愿意重写一遍。它不参与渲染，但影响可读性、调试效率和重构信心。
常见错误是只写 <!-- header --> 这类模糊注释，或者把整块结构塞进一个长注释里，结果改一处，注释全失效。
- 组件级注释建议放在
<section>或<article>开头，用明确作用+上下文说明，比如：<!-- 搜索框：响应式 + 支持键盘聚焦 + 与 header.js 中 initSearch() 绑定 --> - 避免在行内写注释（如
<div class="card" ><!-- 不要这样 -->），容易被压缩工具误删，也破坏标签结构清晰度 - 动态生成的 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”，不是把每个 <header> 单独存成 header.html 就完事。关键看构建链路是否支持、运行时是否引入额外开销。
真实场景中，不同方案差异很大：
- 服务端渲染（PHP / Django / Rails）：可直接
<?php include 'partials/header.php'; ?>，安全、零请求、支持变量传入 - 静态站点（Hugo / Jekyll）：用原生 partial 语法（如
{% include header.html %}），构建时合并，无运行时成本 - 纯前端项目（React/Vue 之外）：若强行用
fetch()加载 HTML 片段，会触发额外请求、阻塞渲染、破坏 SEO，且无法享受浏览器预加载和缓存策略 - Webpack 用户可用
html-webpack-plugin配合html-loader实现 import，但注意：import Header from './header.html'导入的是字符串，需手动插入（如el.innerHTML = Header），不自动绑定事件或初始化脚本
注释和模块化救不了糟糕的 DOM 结构
再详细的注释也掩盖不了嵌套过深、语义错乱、冗余 wrapper 的问题。比如用 5 层 <div> 包裹一个按钮，就算每层都写了注释，别人仍得花 2 分钟理清哪层控制动画、哪层负责响应式断点。
真正提升可维护性的第一道关，是写对结构本身：
- 优先用语义化标签（
<nav>,<aside>,<time>），而非堆<div class="wrapper-inner-container"> - 避免为样式妥协结构——CSS 已支持
display: contents和subgrid，很多“必须加 wrapper”的理由已过时 - 检查
aria-*属性是否随模块复用而同步更新（如aria-labelledby指向的 ID 在片段中是否唯一），否则注释再全，无障碍也崩了
