XML Comments: Complete Guide with Examples

What is XML?

XML (Extensible Markup Language) is a markup language and file format for storing and transmitting data. XML defines the rules for encoding documents in both human-readable and machine-readable formats. XML emphasizes simplicity, versatility, and ease of use on the web. XML is a text data format with strong Unicode support natively supported by many programming languages. While XML is designed for documents, it can represent arbitrary data structures, such as those used in web services. XML is primarily used in enterprise grade applications where increased data reliability and security is required.

What is an XML comment?

In XML and in every programming language, comments play an important role because they can be used to explain a particular piece of code. XML comments are a single-character or paragraph statement that, in addition to code, provides formal documentation and helps you understand common tags used in an XML file. Keep in mind that an inline comment should be used sparingly, as it will make the code harder to read. Comments are possible anywhere in the XML code. Unlike JSON comments, XML comments are supported out of the box. In XML, comments are identified by the following syntax: "<!--”, and their end is indicated by "-->". You can add a text note between these characters.

<!--This is your comment-->

XML Comments Example

The following are examples of XML comments with detailed descriptions:

<?xml version = "1.0" encoding = "UTF-8"?>
<User>
  <!--This is your comment-->
  <Id>3</Id>
  <Name>Leo</Name>
  <Rating>2</Rating>
</User>

How to add comments inside an XML document?

The example below adds a single line comment before the root element, this comment ensures that the entire document is readable to understand the purpose of the tags.

<?xml version = "1.0" encoding = "UTF-8"?>
<User>
  <!--This is your comment-->
  <Id>14</Id>
  <Name>Jack</Name>
  <Rating>6</Rating>
</User>

How to add multiple comments to XML documents?

The following example adds several XML comments to a single XML document:

<?xml version = "1.0" encoding = "UTF-8"?>
<Order>
  <!--First comment: The first comment-->
  <Id>78912</Id>
  <Customer>Jack</Customer>
  <Quantity>6</Quantity>
  <!--Second comment: The second comment-->
  <Price>28.00</Price>
</Order>

How to add multi-line comments to XML documents?

The following example adds multiline XML comments.

<?xml version = "1.0" encoding = "UTF-8"?>
<!-- Multi-line comments 
It's multiline
XML comments
example
-->
<Student>
  <name>Tim</name>
  <grade>B</grade>
</Student>

How to comment out a line block XML?

Unlike other programming languages where you can use different syntaxes for single-line and multi-line comments, XML has only one syntax for multi-line comments. You cannot comment on a single line and automatically end the comment with a line break. But you can still comment out XML nodes like in other programming languages using multi-line XML comments.

<?xml version = "1.0" encoding = "UTF-8"?>
<User>
  <!--Your comment
  <Student>
    <name>Tim</name>
    <grade>A</grade>
  </Student>
  -->
  <Name>Alice</Name>
  <Rating>3</Rating>
</User>

What are invalid XML comments?

When used incorrectly, XML comments can corrupt an XML document and make it unreadable by XML processors. The following are examples of invalid comments in XML.

<!—This is your comment --
Text --> // the sequence of characters is not allowed

<!—This is your comment ---> // invalid end hyphen

<!-- the comment<!-- new comment--> --> // the comment nested within a comment is not allowed

Best practices for XML comments

If you are working with XML comments, you should follow the following rules:

• XML comments cannot be placed before an XML declaration. XML comments must not conflict with the XML declaration
• XML comments cannot be included between attribute elements. XML comments must be enclosed between angle bracket characters.
• Nested comments in XML are not allowed
• Object references not recognized in the XML comments

See also

• What is XML?
• Convert XML to JSON
• Convert JSON to XML
• How do I post XML to the server?