XML —

Leaving a Trail with Comments

It shouldn't come as a surprise that any self-respecting XML developer would want to write clean XML code that is as easy to understand as possible. Part of the process of writing clean XML code is documenting the code whenever necessary. Comments are used in XML to add descriptions to code and include information that isn't part of a document's content. Comments aren't considered part of a document's content because XML processors ignore them.

Technically speaking, it's possible for an XML processor to actually pay attention to comments and not ignore them, which might make sense in an XML development tool such as a WYSIWYM editor. Such a tool might allow you to enter and modify comments through a graphical user interface, in which case it would need to process comments to some degree. Even so, the comments wouldn't be interpreted as document content.

Comments are specified in a document between the <!-- and --> symbols. The only limitation on comments is that you can't include double-hyphens (--) in the body of a comment because they conflict with XML's comment syntax. Following is an example of how you could use a comment to add information to a Tall Tales question in the Tall Tales sample document that you've worked with in previous tutorials:

<!-- This question still needs to be verified.-->
<tt answer="a">
<question>
In 1994, the Nestle UK food company was fined for injuries suffered by a
36 year-old employee at a plant in York, England. What happened to the man?
</question>
<a>
He fell in a giant mixing bowl and was whipped for over a minute.
</a>
<b>
He developed an ulcer while working as a candy bar tester.
</b>
<c>
He was hit in the head with a large piece of flying chocolate.
</c>
</tt>

The information contained within the comment isn't considered part of the document data. The usefulness of comments will naturally vary with the type of XML documents you are creating. Some documents tend to be relatively self-explanatory, whereas others benefit from comments that make them more understandable. In this example, the comment is used to flag a question that still needs to be verified before being incorporated into the final game. In reality, an attribute might provide a better approach for flagging unverified questions but the comment still works as a simpler approach.