HTTP 与 Web 标准 / 系统课时
注释应该写在什么位置
注释应该写在什么位置
XML 注释适合记录字段含义、临时说明和维护信息,但它不是可以随意插入的文本。掌握注释的合法位置以及 -- 等限制,才能避免一条说明文字让整个 XML 文档无法解析。
学习目标
- 掌握 XML 注释的基本语法和常见放置位置
- 判断注释能否出现在元素、标签和 XML 声明附近
- 避免
--、嵌套注释等会破坏文档合法性的写法
注释的基本语法
XML 使用 <!-- 开始注释,以 --> 结束。注释本身不会成为元素的文本内容,解析器通常会把它作为注释节点处理,业务程序是否保留它则取决于所用解析 API 和配置。
下面的文档在根元素内部放置了一条说明,这是最常见也最容易理解的位置:
<?xml version="1.0" encoding="UTF-8"?>
<book>
<!-- price 使用人民币,单位为元 -->
<title>XML 入门</title>
<price>59</price>
</book>注释可以独占一行,也可以出现在元素内容之间。为了方便阅读和后续修改,实际项目通常让注释靠近它所解释的元素,而不是集中堆在文档末尾。
哪些位置可以写注释
注释可以出现在根元素内部,也可以位于根元素之前或之后。需要注意的是,如果文档包含 XML 声明,声明必须保持在文档开头,不能先写注释再写声明。
下面这些位置都是合理的:
<?xml version="1.0" encoding="UTF-8"?>
<!-- 整份文档的用途说明 -->
<catalog>
<!-- 当前仅发布正式商品 -->
<item id="A01">Keyboard</item>
</catalog>
<!-- 文件由导出程序生成 -->根元素外可以有注释,但一个 XML 文档仍然只能有一个文档元素。注释不会成为第二个根元素,因此不会违反这一规则。
不能把注释塞进标签内部
注释不能插进元素的开始标签、结束标签或属性写法中。标签内部属于 XML 标记语法的一部分,解析器期待的是元素名、属性或标签结束符,而不是注释节点。
下面的写法都是非法的:
<book <!-- 临时说明 --> id="B01">
<title>XML</title>
</book>
<book id=<!-- 编号 -->"B01">
<title>XML</title>
</book>如果要解释 id 属性,应把注释放到元素前后,或者通过 XML Schema、DTD、项目文档等方式说明字段约束,而不是把注释嵌入属性语法。
注释内容不能包含连续双连字符
XML 注释中最容易忽略的限制是:注释内容不能出现 --。因此,把连续连字符用作视觉分隔线会直接产生非法 XML。此外,不应让注释正文以单个 - 紧贴结束标记,否则同样会破坏注释语法边界。
下面的注释不合法:
<!-- old--new -->
<!-- -------- -->需要表达类似内容时,可以改用普通文字或其他分隔符:
<!-- old -> new -->
<!-- ======== -->XML 也不支持通过再次写 <!-- ... --> 来嵌套注释。需要暂时屏蔽一大片 XML 时,尤其要检查被包住的区域是否已经含有其他注释;直接在外层再加一组注释标记通常会产生非法的 -- 组合。
注释应该服务于维护而不是隐藏结构
适合写进 XML 注释的是维护者需要看到、但业务数据本身不需要承载的信息,例如字段来源、兼容性提醒或临时迁移说明。长期有效的业务数据、配置开关和状态值则应该建模为元素或属性,不能依赖注释传递给程序。
判断位置是否合法时,可以记住一个简单原则:注释是独立的 XML 节点,不是标签语法的一部分。把它放在元素之间通常安全;一旦试图插进标签、属性、XML 声明或另一条注释内部,就应重新调整位置。