PHP小码农

Appearance

注释规范 ​

HTML 注释是代码文档的重要组成部分。良好的注释习惯能够帮助团队成员快速理解代码结构和意图，便于后续维护和协作。本节将介绍 HTML 注释的语法规范、条件注释（IE 兼容）、注释的使用场景和风格指南。

前置知识

阅读本节前，建议先了解：命名约定

HTML 注释语法 ​

基本语法 ​

html
<!-- 这是单行注释 -->

<!--
  这是多行注释
  可以跨多行
  适合较长的说明
-->

注释中的特殊字符 ​

html
<!-- 注释中不能包含双连字符 -->
<!-- 错误：这-是个-错误的注释 -->

<!-- 正确：使用等号替代 -->
<!-- ============ 分隔线 ============ -->

<!-- 正确：避免连续的连字符 -->
<!-- 这是一段普通的注释文字 -->

注释中的连字符

HTML 注释中不能包含 --，否则会导致解析错误。使用 = 或其他字符替代分隔线。

注释使用场景 ​

1. 区块划分 ​

html
<body>
  <!-- ==================== 页面头部 ==================== -->
  <header class="site-header">
    <nav aria-label="主导航">
      <ul>
        <li><a href="/">首页</a></li>
      </ul>
    </nav>
  </header>

  <!-- ==================== 主内容区域 ==================== -->
  <main class="site-main">
    <!-- 文章列表 -->
    <section class="article-list">
      ...
    </section>

    <!-- 侧边栏 -->
    <aside class="sidebar">
      ...
    </aside>
  </main>

  <!-- ==================== 页面页脚 ==================== -->
  <footer class="site-footer">
    ...
  </footer>
</body>

2. 组件说明 ​

html
<!-- 搜索框组件：支持自动补全和最近搜索 -->
<div class="search-component">
  <label for="search-input">搜索</label>
  <input type="search" id="search-input" autocomplete="off" />
  <div class="search-suggestions" aria-live="polite">
    <!-- 搜索建议由 JavaScript 动态填充 -->
  </div>
</div>

<!-- 用户头像组件：未上传时显示默认头像 -->
<div class="user-avatar" data-js="user-avatar">
  <img src="default-avatar.svg" alt="用户头像" />
  <button class="user-avatar__upload" data-js="avatar-upload">
    上传头像
  </button>
</div>

3. 临时注释和 TODO ​

html
<!-- TODO: 添加分页功能 -->
<div class="product-list">
  ...
</div>

<!-- HACK: 临时修复 Safari 中的布局问题 -->
<!-- 参考：https://bugs.webkit.org/show_bug.cgi?id=12345 -->
<style>
  @supports not (-webkit-backdrop-filter: blur(1px)) {
    .card { backdrop-filter: none; }
  }
</style>

<!-- FIXME: 移动端点击事件有延迟 -->
<button class="btn" data-js="submit">提交</button>

<!-- NOTE: 这个组件将在下一个版本中替换 -->
<div class="old-component">
  ...
</div>

4. 版权和许可证 ​

html
<!--
  版权所有 2024 公司名称
  保留所有权利

  本代码遵循 MIT 许可证
  https://opensource.org/licenses/MIT
-->

5. 条件注释（IE 兼容） ​

html
<!--[if IE]>
  <div class="ie-warning">
    您正在使用 Internet Explorer，建议升级到现代浏览器。
  </div>
<![endif]-->

<!--[if lt IE 9]>
  <script src="html5shiv.min.js"></script>
<![endif]-->

<!--[if IE 8]>
  <link rel="stylesheet" href="ie8.css" />
<![endif]-->

<!-- 仅非 IE 浏览器加载 -->
<!--[if !IE]><!-->
  <link rel="stylesheet" href="modern.css" />
<!--<![endif]-->
条件说明
[if IE]所有 IE 版本
[if IE 8]仅 IE 8
[if lt IE 9]IE 9 以下
[if lte IE 9]IE 9 及以下
[if gt IE 8]IE 8 以上
[if gte IE 9]IE 9 及以上
[if !IE]非 IE 浏览器

条件注释的现状

条件注释仅在 IE10 及以下有效。现代项目通常不再需要条件注释，但仍可能在维护旧项目时遇到。

注释风格指南 ​

推荐格式 ​

html
<!-- 组件名称：简要说明（一行） -->
<!-- 更多细节可以放在第二行 -->

<!-- 用户导航栏 -->
<nav class="user-nav">
  ...
</nav>

<!-- 产品卡片：显示商品图片、名称、价格和购买按钮 -->
<article class="product-card">
  ...
</article>

注释位置 ​

html
<!-- 推荐：注释在元素上方 -->
<!-- 页面标题 -->
<h1>HTML5 教程</h1>

<!-- 推荐：紧跟在开始标签后（用于复杂区块） -->
<div class="complex-component">
  <!-- 说明这个组件的用途和结构 -->
  <div class="inner">
    ...
  </div>
</div>

<!-- 不推荐：注释在元素同一行 -->
<h1>HTML5 教程</h1> <!-- 页面标题 -->

结束标签注释 ​

对于较长的嵌套结构，可以在结束标签处添加注释：

html
<!-- 主内容开始 -->
<main class="site-main">
  <section class="hero">
    ...
  </section>

  <section class="features">
    ...
  </section>
</main>
<!-- /主内容结束 -->

<!-- 产品列表开始 -->
<div class="product-list">
  <div class="product-item">...</div>
  <div class="product-item">...</div>
</div>
<!-- /产品列表结束 -->

注释与无障碍 ​

注释内容不会被屏幕阅读器播报，也不会影响页面渲染：

html
<!-- 这个注释对用户和屏幕阅读器都不可见 -->
<!-- 但 HTML 中的可见注释需要避免 -->

<!-- 错误：注释中的特殊字符可能被解析 -->
<!-- 价格 ¥<100 的商品 -->

<!-- 正确：使用实体或避免特殊字符 -->
<!-- 价格低于100元的商品 -->

实战示例：完整注释的页面 ​

html
<!DOCTYPE html>
<!--
  产品详情页
  作者：前端团队
  更新：2024-01-15
  说明：展示单个产品的详细信息、规格和评价
-->
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>产品详情 - 产品名称</title>

  <!-- 全局样式 -->
  <link rel="stylesheet" href="css/base.css">
  <!-- 布局样式 -->
  <link rel="stylesheet" href="css/layout.css">
  <!-- 组件样式 -->
  <link rel="stylesheet" href="css/components.css">
</head>
<body>
  <!-- 跳过导航链接 -->
  <a href="#main" class="skip-link">跳到主要内容</a>

  <!-- ============= 页面头部 ============= -->
  <header class="site-header">
    <!-- 品牌导航 -->
    <nav class="brand-nav" aria-label="品牌导航">
      <a href="/" class="brand-nav__logo">品牌</a>
    </nav>
  </header>

  <!-- ============= 面包屑导航 ============= -->
  <nav class="breadcrumb" aria-label="面包屑">
    <ol>
      <li><a href="/">首页</a></li>
      <li><a href="/products">产品</a></li>
      <li aria-current="page">产品名称</li>
    </ol>
  </nav>

  <!-- ============= 主内容区域 ============= -->
  <main id="main" class="site-main">
    <!-- 产品基本信息 -->
    <section class="product-info">
      <div class="product-gallery">
        <!-- 产品图片轮播 -->
        <div class="gallery">
          <img src="product-1.jpg" alt="产品正面视图" />
          <img src="product-2.jpg" alt="产品侧面视图" />
        </div>
      </div>

      <div class="product-details">
        <h1 class="product-title">产品名称</h1>
        <p class="product-price" data-price="299.00">¥299.00</p>
        <p class="product-description">产品简介...</p>

        <!-- 购买按钮区域 -->
        <div class="product-actions">
          <button class="btn btn--primary" data-js="add-to-cart">
            加入购物车
          </button>
          <button class="btn btn--secondary" data-js="add-to-wishlist">
            收藏
          </button>
        </div>
      </div>
    </section>

    <!-- 产品规格 -->
    <section class="product-specs" aria-labelledby="specs-heading">
      <h2 id="specs-heading">产品规格</h2>
      <table>
        <caption>产品详细规格表</caption>
        <tbody>
          <tr>
            <th scope="row">重量</th>
            <td>200g</td>
          </tr>
        </tbody>
      </table>
    </section>

    <!-- TODO: 添加用户评价区域 -->
  </main>

  <!-- ============= 页面页脚 ============= -->
  <footer class="site-footer">
    <p>&copy; 2024 品牌</p>
  </footer>

  <!-- 全局脚本 -->
  <script src="js/main.js"></script>
</body>
</html>

注意事项 ​

  1. 注释要有价值：不要注释显而易见的代码，注释"为什么"而非"是什么"
  2. 避免过期注释：及时更新或删除不再准确的注释
  3. 不要在注释中包含敏感信息：密码、API 密钥等
  4. 保持注释格式一致：统一的注释风格降低认知负担
  5. TODO 注释要追踪：定期清理 TODO 注释

最佳实践 ​

  • 使用 <!-- --> 语法进行 HTML 注释
  • 注释放在被注释元素的上方
  • 区块划分使用明显的分隔注释
  • 组件注释包含组件名称和用途说明
  • 使用 TODO/FIXME/NOTE 等前缀标记待办事项
  • 复杂的结束标签添加结束注释
  • 定期审查和更新注释

下一节

继续学习：HTMLLint 验证

参考链接 ​