XML Comments and Processing Instructions

XML provides two special constructs that are not part of the data itself but serve important supporting roles: comments and processing instructions. Comments help developers document their XML files, while processing instructions pass information directly to the application that processes the file.

XML Comments

A comment in XML is a note written inside the document that is completely ignored by XML parsers. Comments are used to explain the structure of the document, leave notes for other developers, or temporarily disable parts of the XML for testing.

Comment Syntax

<!-- This is a comment -->

A comment begins with <!-- and ends with -->. Everything between these markers is ignored during processing.

Single-Line Comment

<inventory>
  <!-- List of available products -->
  <item>Keyboard</item>
  <item>Monitor</item>
</inventory>

Multi-Line Comment

<settings>
  <!-- 
    Configuration for the payment module.
    Last updated: March 2024.
    Do not change the currency code without authorization.
  -->
  <currency>USD</currency>
  <tax_rate>0.08</tax_rate>
</settings>

Using Comments to Disable XML Content

During development or debugging, it is common to "comment out" part of an XML document temporarily to isolate an issue.

<config>
  <database>production_db</database>
  <!-- <database>test_db</database> -->
</config>

The second <database> element is wrapped in a comment, so it will be ignored. Only the first one is active.

Rules for XML Comments

Comments in XML follow specific restrictions that must be respected:

• Comments cannot appear before the XML declaration on line one.
• Comments cannot be nested — placing one comment inside another is not allowed.
• The sequence -- (double hyphen) cannot appear inside the comment text itself, except at the very end.
• Comments can appear almost anywhere in an XML document: before or after the root element, or between elements.

Invalid: Nested Comments

<!-- Outer comment <!-- inner comment --> still outer -->

This is not allowed. Once the first --> is encountered, the parser considers the comment closed.

Invalid: Double Hyphen Inside Comment

<!-- Note: this is option 1 -- option 2 is deprecated -->

The -- in the middle causes a parsing error. Rewrite it to avoid the double hyphen:

<!-- Note: option 1 is current; option 2 is deprecated -->

Processing Instructions

A processing instruction (PI) is a special directive in an XML document intended for the application that will process the file — not for the XML parser itself. Processing instructions allow the XML author to pass instructions or hints to specific software.

Processing Instruction Syntax

<?target instruction?>

• Starts with <? and ends with ?>.
• The target is the name of the application or system the instruction is meant for.
• The instruction is additional information passed to that application.

The XML Declaration Is a Processing Instruction

The XML declaration at the top of a file is technically a processing instruction directed at the XML processor itself.

<?xml version="1.0" encoding="UTF-8"?>

Example: Linking an XML File to a Stylesheet

A processing instruction can tell a browser to apply a CSS stylesheet when displaying the XML file.

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css" href="style.css"?>
<catalog>
  <item>Laptop</item>
  <item>Tablet</item>
</catalog>

The second line tells the browser: "Use the file style.css to style this XML document."

Example: Custom Application Instruction

<?xml version="1.0" encoding="UTF-8"?>
<?report format="pdf" orientation="landscape"?>
<sales>
  <region>North</region>
  <total>48200</total>
</sales>

This custom processing instruction tells a hypothetical report-generating application to output the data as a PDF in landscape orientation. The XML parser ignores this instruction — only the reporting application knows what to do with it.

Differences Between Comments and Processing Instructions

Practical Full Example

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="transform.xsl"?>
<!-- Book inventory for the downtown store branch -->
<inventory branch="downtown">
  <!-- Fiction section -->
  <book id="B001">
    <title>The Great Adventure</title>
    <author>Jane Doe</author>
    <stock>30</stock>
  </book>
  <!-- Non-fiction section -->
  <book id="B002">
    <title>History of Science</title>
    <author>Alan Webb</author>
    <stock>15</stock>
  </book>
</inventory>

Key Points

• Comments are written using <!-- ... --> and are ignored by parsers.
• Comments help document the XML file for human readers.
• Comments cannot be nested and cannot contain -- in the middle of the text.
• Processing instructions use <?target data?> syntax and send directives to the processing application.
• The XML declaration at the top of a file is itself a processing instruction.
• A common processing instruction links an XML file to a stylesheet for display or transformation.