Skip to main content

XML Comments

In any form of code, comments are essential for making the content understandable to other developers (and your future self). XML is no exception. Comments in XML are used to add explanatory notes, provide context, or temporarily "disable" a block of markup without deleting it.

An XML comment is a piece of text within an XML document that is completely ignored by the XML parser. It is intended solely for human readers and has no effect on the data or structure of the document.

Basic Syntax​

The syntax for a comment in XML is identical to the syntax in HTML.

Syntax: <!-- Your comment text goes here -->

  • It begins with <!-- (less than, exclamation mark, two hyphens).
  • It ends with --> (two hyphens, greater than).

Example:

<!-- This is a comment describing the book element below. -->
<book category="web">
    <title>Learning XML</title>
</book>

Fundamental Rules for XML Comments​

While the syntax is simple, there are a few strict rules you must follow.

Comments Cannot Contain Double-Hyphens (--)​

The string -- is not allowed anywhere inside the comment's text. This is because it is used to signal the end of the comment, and its appearance elsewhere would confuse the parser.

  • Correct: <!-- This is a valid comment -->
  • Incorrect: <!-- This is an invalid -- comment --> (This will cause a parsing error).

Comments Cannot Be Nested​

You can not place one comment inside another.

  • Incorrect: 
    <!-- Outer Comment <!-- Inner Comment --> -->
    The parser would see the first --> and consider the "Outer Comment" to be closed, leaving the final --> as an invalid, orphaned piece of markup.

Comments Cannot Appear Before the XML Declaration​

If your document includes an XML declaration (<?xml ... ?>), it must be the very first thing in the file. No comments or whitespace can precede it.

  • Correct: 
    <?xml version="1.0" encoding="UTF-8"?>
    <!-- This is a valid comment -->
    <root/>
  • Incorrect: 
    <!-- This comment is in an invalid position -->
    <?xml version="1.0" encoding="UTF-8"?>
    <root/>

Comments Cannot Be Inside a Tag​

Comments can appear between elements, but not within the angle brackets of a start-tag or an end-tag.

  • Correct: <root><!-- comment --></root>
  • Incorrect: <root <!-- comment -->>

Practical Examples of Using Comments​

Explaining a Section​

<!-- User data section. Sourced from the primary database. -->
<users>
  ...
</users>

Temporarily "Commenting Out" a Block of XML​

This is a very common technique during development and debugging. You can disable a section of your XML without deleting it.

<bookstore>
  <book>
    <title>Book One</title>
  </book>
  
  <!-- Temporarily removed this book for testing -->
  <!--
  <book>
    <title>Book Two</title>
  </book>
  -->
  
  <book>
    <title>Book Three</title>
  </book>
</bookstore>

Conclusion​

XML comments are a simple but vital tool for documenting your data and aiding in development.

  • Always use the correct syntax: <!-- comment -->.
  • Remember the key rules: no double-hyphens inside, no nesting, and no comments before the XML declaration.
  • Use comments to explain complex parts of your XML or to temporarily disable blocks of code during testing.

Table of Contents