HTTP 与 Web 标准 / 系统课时

注释应该写在什么位置

注释应该写在什么位置

XML 注释适合记录字段含义、临时说明和维护信息,但它不是可以随意插入的文本。掌握注释的合法位置以及 -- 等限制,才能避免一条说明文字让整个 XML 文档无法解析。

学习目标

  • 掌握 XML 注释的基本语法和常见放置位置
  • 判断注释能否出现在元素、标签和 XML 声明附近
  • 避免 --、嵌套注释等会破坏文档合法性的写法

注释的基本语法

XML 使用 <!-- 开始注释,以 --> 结束。注释本身不会成为元素的文本内容,解析器通常会把它作为注释节点处理,业务程序是否保留它则取决于所用解析 API 和配置。

下面的文档在根元素内部放置了一条说明,这是最常见也最容易理解的位置:

xml
<?xml version="1.0" encoding="UTF-8"?>
<book>
  <!-- price 使用人民币,单位为元 -->
  <title>XML 入门</title>
  <price>59</price>
</book>

注释可以独占一行,也可以出现在元素内容之间。为了方便阅读和后续修改,实际项目通常让注释靠近它所解释的元素,而不是集中堆在文档末尾。

哪些位置可以写注释

注释可以出现在根元素内部,也可以位于根元素之前或之后。需要注意的是,如果文档包含 XML 声明,声明必须保持在文档开头,不能先写注释再写声明。

下面这些位置都是合理的:

xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- 整份文档的用途说明 -->
<catalog>
  <!-- 当前仅发布正式商品 -->
  <item id="A01">Keyboard</item>
</catalog>
<!-- 文件由导出程序生成 -->

根元素外可以有注释,但一个 XML 文档仍然只能有一个文档元素。注释不会成为第二个根元素,因此不会违反这一规则。

不能把注释塞进标签内部

注释不能插进元素的开始标签、结束标签或属性写法中。标签内部属于 XML 标记语法的一部分,解析器期待的是元素名、属性或标签结束符,而不是注释节点。

下面的写法都是非法的:

xml
<book <!-- 临时说明 --> id="B01">
  <title>XML</title>
</book>

<book id=<!-- 编号 -->"B01">
  <title>XML</title>
</book>

如果要解释 id 属性,应把注释放到元素前后,或者通过 XML Schema、DTD、项目文档等方式说明字段约束,而不是把注释嵌入属性语法。

注释内容不能包含连续双连字符

XML 注释中最容易忽略的限制是:注释内容不能出现 --。因此,把连续连字符用作视觉分隔线会直接产生非法 XML。此外,不应让注释正文以单个 - 紧贴结束标记,否则同样会破坏注释语法边界。

下面的注释不合法:

xml
<!-- old--new -->
<!-- -------- -->

需要表达类似内容时,可以改用普通文字或其他分隔符:

xml
<!-- old -> new -->
<!-- ======== -->

XML 也不支持通过再次写 <!-- ... --> 来嵌套注释。需要暂时屏蔽一大片 XML 时,尤其要检查被包住的区域是否已经含有其他注释;直接在外层再加一组注释标记通常会产生非法的 -- 组合。

注释应该服务于维护而不是隐藏结构

适合写进 XML 注释的是维护者需要看到、但业务数据本身不需要承载的信息,例如字段来源、兼容性提醒或临时迁移说明。长期有效的业务数据、配置开关和状态值则应该建模为元素或属性,不能依赖注释传递给程序。

判断位置是否合法时,可以记住一个简单原则:注释是独立的 XML 节点,不是标签语法的一部分。把它放在元素之间通常安全;一旦试图插进标签、属性、XML 声明或另一条注释内部,就应重新调整位置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

注释应该写在什么位置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通