语义标签错误使用注释掩盖问题，应优先用<header><nav><main>等替代div；class命名需遵循BEM规范，状态用is-active前缀；注释须可被工具校验，复用片段需含@name/@props/@example三要素。
HTML语义标签用错，注释就成遮羞布
很多团队把 <div class="header"> 当成万能解，再配上“”这种注释，实际是掩盖结构缺陷。语义标签本身已是文档契约：用 <header> 就不该再加说明性注释；反之，若非得靠注释解释 <div id="nav-wrapper"> 是导航，说明该换 <nav>。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 优先用
<main>、<section>、<aside>替代无意义的<div>嵌套 - 注释只用于非常规场景（如
<!-- TODO: 待接入SSR，当前为CSR降级方案 -->），不解释语义 - 禁用
<!-- header start -->/<!-- header end -->这类包裹式注释——它们暴露了标签不可信
class命名没契约，CSS和JS都会踩坑
btn-primary-active-hover 看似清晰，实则把状态、样式、交互耦合进名字里，导致 JS 查找元素时写 document.querySelector('.btn-primary-active-hover')，一旦状态变化就得改 JS 和 class 名，维护成本翻倍。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 采用 BEM 或类似约定，例如
button--primary（修饰符） +button__icon（元素），状态用is-active这类统一前缀 - JS 操作应基于
data-*属性，比如data-action="submit"，而非依赖 class 名字结构 - 避免在 class 中嵌入技术细节，如
js-dropdown-trigger—— 改用data-trigger="dropdown"
注释不是写给机器看的，但必须让机器能验证
纯手工注释（如 <!-- 用户资料卡片，含头像、昵称、等级 -->）无法被工具检查，也容易过期。真正可维护的注释要能被 linter 或自定义脚本识别。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 用
<!-- @component UserCard -->这类带命名空间的注释，配合 ESLint 插件或自定义 HTML 静态扫描脚本校验组件边界 - 关键区块加
<!-- @required-attr data-user-id -->，用于 CI 阶段检查必要属性是否缺失 - 禁止注释中出现“此处勿删”“临时方案”等主观描述；替换为可执行标记，如
<!-- @deprecated v2.1 use <UserBadge> instead -->
模板片段复用时，注释和命名必须同步演进
一个 <include src="components/cta-button.html"> 被十处引用，但只有其中三处加了 <!-- CTA按钮：主流程跳转 --> 注释，其余地方靠猜——这就是命名契约断裂的典型表现。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有复用片段的顶层注释必须包含
@name、@props、@example三要素，例如：<!-- @name Button @props {type: "primary|secondary", size: "sm|md"} @example <Button type="primary" size="md">Click</Button> --> - 构建时用
html-validate或自定义正则扫描缺失@name的 include 标签 - 当
Button组件新增disabled属性，必须同步更新所有@props注释，CI 流水线应失败并提示
注释和命名不是写完就扔的副产品，它们是 HTML 接口契约的一部分——没人会忽略 API 文档的准确性，也不该容忍 class 或 <!--> 里的模糊地带。
