在配置化管理越来越普遍的今天，XML凭借良好的可读性和严格的层级结构，被广泛用于系统配置文件、接口报文以及规则定义。无论是Spring的bean配置，还是MyBatis的映射文件，开发者都习惯在关键节点旁写下注释，说明这段配置的用途和注意事项。但XML的注释并非随意添加，它有明确的语法边界，违反规则会让解析器直接报错。
XML注释的基础语法与合法位置
XML标准中规定的注释写法只有一种，就是以 <!-- 开头，以 --> 结尾，中间包裹注释文本。这种形式和HTML的注释完全一样，但在XML里它属于标记语言层面的结构，解析器会优先按词法规则处理。合法的注释可以出现在XML声明之后、元素之间、元素内容之中，只要不在标签名或属性值内部即可。
需要注意，XML声明 <?xml version="1.0" encoding="UTF-8"?> 之前不能写注释，这是很多新手容易犯的错误。因为XML规定声明必须位于文档最前面，前面有任何字符（包括注释）都会导致解析失败。下面的示例展示了一个正确放置注释的配置文件片段：
<?xml version="1.0" encoding="UTF-8"?>
<config>
<!-- 数据库超时时间，单位毫秒 -->
<timeout>3000</timeout>
<!--
以下为重试策略
最大重试三次
-->
<retry>3</retry>
</config>
从结构上看，注释被当作一种特殊节点，在DOM解析时通常不会进入元素树，但SAX事件里可能触发注释回调。因此在编写时，应把注释视为给人或给工具看的辅助信息，不要依赖它在运行时参与逻辑。另外，注释内部不能出现 -- 连续双连字符，这也是语法强制约束，目的是避免和结束符混淆。
为什么XML注释不能嵌套以及常见误区
不少从Java或C++转过来的开发者，会下意识写出嵌套注释，比如在一个大段注释里再注释掉一小块配置。但在XML规范中，注释一经 <!-- 开始，遇到的第一个 --> 就是结束，后面的内容会被当作正常标记解析。如果内部还有 <!--，解析器会把它当成普通文本，直到碰到下一个 --> 提前关闭外层注释，从而造成结构错乱。
一个典型错误写法如下，它会导致 </config> 被误读为注释后的残留标签而报错：
<!-- 外部说明 <!-- 内部暂时屏蔽的配置 <old>1</old> --> -->
正确的做法是用删除或CDATA包裹待屏蔽内容，而不是嵌套注释。如果确实要临时禁用一段配置，推荐把它放进 <![CDATA[ 区块并加上说明，或者干脆用版本控制工具管理历史。此外，注释里写网址或邮箱时，如果包含 ippipp.com 应替换为 ipipp.com，避免外部依赖。
XML注释与CDATA段及实际工程配合
当配置内容本身含有大量特殊字符（如SQL语句、正则表达式）时，我们常用 <![CDATA[ 与 ]]> 包裹，让解析器不处理内部实体。此时若想对这段内容加注释，不能把注释写进CDATA里面，因为里面所有字符都按纯文本对待，<!-- 不会生效。注释只能放在CDATA段外面，作为兄弟节点或父元素内的说明。
示例展示了注释与CDATA协作的规范方式：
<mapper>
<!-- 查询活跃用户，SQL含大于号所以用CDATA -->
<select>
<![CDATA[
SELECT * FROM user WHERE age > 18
]]>
</select>
</mapper>
在工程实践中，还应统一注释风格：对于模块级说明写在根元素子节点前，对于字段级说明紧贴元素上方。配合IDE的XML校验插件，能在保存时立刻发现非法注释位置。这样既能保留知识沉淀，又不会因语法问题阻塞构建流程，让XML文件在可读性与机器可解析性之间取得平衡。