5. XML Comments and Special Characters

What you will learn

How to write comments in XML
The rules that keep comments valid
Entity references and numeric character references
When to use CDATA, and a note on encoding

XML comments

XML comments look exactly like HTML comments. A parser ignores them, but people reading the file see them.

XML code

<?xml version="1.0" encoding="UTF-8"?>
<!-- A list of two books -->
<library>
  <book>Learning XML</book>
  <!-- <book>Learning PHP</book> (switched off for now) -->
</library>

What a program sees

One book element only. The second book is inside a comment, so it is not part of the data.

Comment rules

A comment starts with .
It must not contain two hyphens in a row (--) inside the text, and must not end with a hyphen before the closing -->.
It cannot go before the XML declaration. The declaration must come first in the file.
It cannot go inside a tag, such as between attributes.
Comments cannot be nested.

XML code: wrong

<!-- Note -- this double hyphen is not allowed -->
<item <!-- not allowed here --> id="1"/>

Comments are visible to anyone who opens the file. Never store passwords or private notes in them.

Processing instructions

A processing instruction passes a message to the program that reads the file. You have already met one: the XML declaration. A common other one links a stylesheet, as you will see in the CSS lesson.

XML code

<?xml-stylesheet type="text/css" href="style.css"?>

The five predefined entities

Some characters mean something to the parser. To use them as plain text, write an entity reference: an ampersand, a name, and a semicolon.

Character	Write	Required?
`<`	`<`	Always, in text and attributes
`&`	`&`	Always
`>`	`>`	Only after `]]`, but escaping it is good habit
`"`	`"`	Inside a double-quoted attribute value
`'`	`'`	Inside a single-quoted attribute value

XML code

<note>Q&amp;A: is 5 &lt; 10 and 10 &gt; 5?</note>
<quote text="She said &quot;hi&quot;"/>

What the text means after parsing

Q&A: is 5 < 10 and 10 > 5?
She said “hi”

Numeric character references

Any character can be written by its Unicode number: decimal as ©, or hexadecimal as ©.

XML code

<footer>&#169; 2026 &#x20AC;5.00</footer>

What the text means after parsing

XML does not know HTML names such as   or ©. Using them in a plain XML file is an error unless you declare them yourself. Use the numeric form, or type the real character in a UTF-8 file.

CDATA for larger blocks

When text contains many special characters, such as a code sample, a CDATA section saves escaping each one.

XML code

<sample><![CDATA[ if (a < b && c > d) { run(); } ]]></sample>

Everything inside <![CDATA[ ... ]]> is plain text. The one thing it cannot contain is the sequence ]]>. CDATA cannot be used inside attribute values.

Encoding

The encoding in the declaration must match how the file is actually saved. Use UTF-8 for both. If the file is saved in another encoding while the declaration says UTF-8, accented letters and non-Latin text turn into garbage, or the parser rejects the file. In Visual Studio Code, the encoding shows at the bottom right of the window.

Common mistakes

Typing a raw & or < in text.
Using HTML entity names such as  .
Putting a comment before the XML declaration.
Using -- inside a comment.
Saving the file in a different encoding from the one declared.
Leaving secrets in comments.

Exercise

Write an element <title> whose text reads Tom & Jerry: 5 < 10. Then add a comment above it saying Cartoon title.

Show solution

<!-- Cartoon title -->
<title>Tom &amp; Jerry: 5 &lt; 10</title>

A parser reads the title as Tom & Jerry: 5 < 10.

Knowledge check

1. How does an XML comment begin and end?

It begins with .

2. How do you write an ampersand in XML text?

&

3. Is   valid in plain XML?

No. Use a numeric reference such as  .

Summary

Comments use , never contain --, and never go before the declaration.
Escape special characters with the five predefined entities or numeric references.
Use CDATA for blocks of raw text, and save the file in the encoding you declare.