HTML5作为当前主流的前端标记语言，代码注释是开发过程中不可或缺的部分，合理的注释能让代码逻辑更清晰，也方便后续维护和团队协作。HTML5的注释语法和之前的HTML版本保持一致，没有新增特殊的注释规则，核心是使用特定的标记包裹注释内容。
HTML5基础注释语法
HTML5的标准注释以<!--开头，以-->结尾，所有被这两个标记包裹的内容都会被浏览器忽略，不会在页面中渲染。不管是单行注释还是多行注释，都遵循这个规则，没有单独的语法区分。
基础的单行注释写法如下：
<!-- 这是单行注释，用于说明下方div的作用 --> <div class="header">网站头部</div>
多行注释只需要把内容放在开头和结尾标记之间即可，不需要额外的换行标记：
<!-- 这是多行注释 可以写多行说明内容 比如描述整个模块的功能、作者、创建时间等信息 --> <section class="content"> <p>内容区域</p> </section>
HTML5注释使用规范
为了让注释发挥最大作用，需要遵循一定的规范，避免随意书写无意义的注释：
- 注释内容要精准：不要写“这里是div”这类冗余内容，要说明这个元素的作用、关联的逻辑，比如“商品列表容器，最多展示10条商品数据”。
- 避免过度注释：简单的、语义明确的代码不需要额外注释，比如
<h1>网站标题</h1>就不需要再注释说明这是网站标题。 - 特殊场景标注：如果是临时注释掉的代码，要标注注释原因和预计恢复时间，避免后续维护时不知道是否需要保留。
- 模块级注释区分：对于大的功能模块，可以在开头和结尾都加注释，标注模块的起始和结束，方便快速定位代码。
模块级注释的示例如下：
<!-- 轮播图模块开始 -->
<div class="carousel">
<ul class="carousel-list">
<li>轮播图1</li>
<li>轮播图2</li>
</ul>
</div>
<!-- 轮播图模块结束 -->
基于HTML5注释的文档生成工具
规范的HTML5注释还可以配合工具自动生成项目文档，减少手动编写文档的工作量，常用的工具如下：
| 工具名称 | 适用场景 | 核心特点 |
|---|---|---|
| JSDoc | 前端项目通用 | 支持HTML、JavaScript注释解析，可生成API文档，配置灵活 |
| VuePress | Vue相关项目 | 可解析项目中的注释生成静态文档站点，支持自定义主题 |
| Docute | 轻量项目 | 无需复杂配置，可快速基于注释生成轻量文档页面 |
JSDoc配合HTML5注释的使用示例
首先需要在HTML的注释中按照JSDoc的规范书写注释，比如给自定义组件加说明：
<!--
@component 自定义按钮组件
@param {string} text - 按钮显示的文字
@param {string} type - 按钮类型，可选值为primary、default
@example
<my-button text="提交" type="primary"></my-button>
-->
<template id="my-button">
<button class="btn"></button>
</template>
然后在项目根目录配置JSDoc的配置文件，运行生成命令后，就可以自动提取注释生成对应的组件文档，所有参数的说明、使用示例都会自动展示在文档中。
注意事项
在书写HTML5注释时，需要注意不要在注释内容中包含--，因为浏览器会把--当成注释的结束标记，导致后续的注释内容失效。比如下面的写法是错误的：
<!-- 这是错误的注释 -- 中间有双横线 -->
正确的写法可以把双横线换成单横线或者其他符号：
<!-- 这是正确的注释 - 中间用单横线分隔 -->
另外，HTML5注释不能嵌套使用，在一个注释内部再写<!--会导致注释解析异常，需要避免这种情况。