下面给你整理一份详解 XML 中代码注释书写方法的系统指南，涵盖语法、规范、注意事项与实用技巧。

📘 一、XML 注释的基本概念

  • 定义：注释是 XML 文档中不会被解析器执行的文本，用于解释文档、给开发者提示、保留说明。
  • 特点：
    1. 不参与 XML 数据结构
    2. 不影响程序逻辑
    3. 仅供人阅读

📘 二、XML 注释的基本语法

<!-- 这是一个注释 -->
  • 注释以 <!-- 开始
  • 以 --> 结束
  • 注释内容可以包含任意文本，但 不能包含连续的两个减号 --

示例：

&lt;note>
    &lt;!-- 这是收件人信息 -->
    &lt;to>Tom&lt;/to>
    &lt;!-- 发送人 -->
    &lt;from>Jerry&lt;/from>
&lt;/note>

📘 三、注释的规则与注意事项

  1. 不能在注释中使用 --

错误示例：

&lt;!-- 这是一个--错误注释 -->

正确做法：

&lt;!-- 这是一个正确的注释 -->
&lt;!-- 如果需要减号，可写成 - - 或者省略 -->
  1. 不能以 > 开始或 <! 开始注释内容

错误示例：

&lt;!-- > 错误 -->
&lt;!-- &lt;! 错误 -->
  1. 可以跨行书写
&lt;!-- 
这是一个跨行注释
可用于长说明
-->
  1. 注释不能嵌套
&lt;!-- 外层 &lt;!-- 内层 --> -->  ❌ 错误

📘 四、注释的实用技巧

1️⃣ 用于文档结构说明

&lt;bookstore>
    &lt;!-- 每个 book 元素表示一本书 -->
    &lt;book>
        &lt;title>XML指南&lt;/title>
    &lt;/book>
&lt;/bookstore>

2️⃣ 用于暂时屏蔽代码（调试用）

&lt;bookstore>
    &lt;!--
    &lt;book>
        &lt;title>测试书籍&lt;/title>
    &lt;/book>
    -->
&lt;/bookstore>

注意：注释仅屏蔽代码，不改变 XML 根元素数量或结构错误。

3️⃣ 用于团队协作与版本说明

&lt;!-- 作者：阿杰 -->
&lt;!-- 创建时间：2025-11-24 -->

4️⃣ 配合 XSLT 或样式表

注释不会影响 XML 解析，可作为 XSLT 的参考信息。

&lt;!-- 此部分由前端样式表渲染 -->
&lt;content>...&lt;/content>

📘 五、DOM 与注释处理

  1. DOM 解析器
  • 注释会生成 Comment 节点
  • 可以通过 .nodeType === Node.COMMENT_NODE 访问

Java 示例：

NodeList list = doc.getChildNodes();
for (int i = 0; i &lt; list.getLength(); i++) {
    Node node = list.item(i);
    if (node.getNodeType() == Node.COMMENT_NODE) {
        System.out.println(node.getNodeValue());
    }
}
  1. SAX 解析器
  • 注释触发 LexicalHandler.comment() 回调
  • 可在事件处理函数中获取注释内容
  1. Python lxml
for comment in tree.xpath('//comment()'):
    print(comment.text)

📘 六、注释书写最佳实践

  1. 保持简短：注释不要过长，关键点即可
  2. 遵循规范：避免 --，不嵌套
  3. 使用注释标记版本/作者信息
  4. 调试阶段可屏蔽元素，但生产环境避免大量注释
  5. 尽量配合缩进与排版，提高可读性

📘 七、示例整合

&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;!-- 文档说明：示例 XML 注释使用 -->
&lt;note>
    &lt;!-- 收件人 -->
    &lt;to>Tom&lt;/to>
    &lt;!-- 发件人 -->
    &lt;from>Jerry&lt;/from>
    &lt;!-- 邮件标题 -->
    &lt;heading>提醒&lt;/heading>
    &lt;!-- 邮件内容 -->
    &lt;body>记得交作业！&lt;/body>
&lt;/note>

解析器会忽略注释内容，但 DOM 或 SAX 可访问。