Comments

Comments provide a way  to insert into an XML document text that isn't really part of the document, but rather is intended for people who are reading the XML source itself.

Anyone who has used a programming language will be familiar with the idea of comments: you want to be able to annotate your code (or your XML), so that those coming after you will be able to figure out what you were doing. (And remember: the one who comes after you may be you! Code you wrote six months ago might be as foreign to you as code someone else wrote.)

Of course, comments may not be as relevant to XML as they are to programming languages; after all, this is just data, and it's self-describing to boot. But you never know when they're going to come in handy, and there are cases where comments can be very useful, even in data.

Comments start with the string <!-- and end with the string -->, as shown here:

There are a couple of points that we need to note about comments. First, you can't have a comment inside a tag, so the following is illegal:

Second, you can't use the string -- inside a comment, so the following is also illegal:

The XML specification states that an XML parser doesn't need to pass these comments on to the application, meaning that you should never count on being able to use the information inside a comment from your application.

Try It Out - Some Comments On Al's CD

Since we've only included a couple of the songs from this fine album in our document, perhaps we should inform others that this is the case. That way some kind soul may finish the job for us!

Open up your cd2.xml file, make the following changes, and save the modified XML file as cd3.xml:

View this in IE5:

How It Works

With the new comments, anyone who reads the source for our XML document will be able to see that there are actually more than two songs on "Dare To Be Stupid". Furthermore, they can see some information regarding the <date-released> element, which may help them in writing applications that work with this information.

In this example, the XML parser included with IE5 does pass comments up to the application, so IE5 has displayed our comments. But remember that a lot of the time, for all intents and purposes this information is only available to people reading the source file. The information in comments may or may not be passed up to our application, depending on which parser we're using. We can't count on it, unless we specifically choose a parser that does pass them through. This means that the application has no way to know whether or not the list of songs included here is comprehensive.

Try It Out - Making Sure Comments Get Seen

If we really need this information, we should add in some real markup to indicate it.

Modify cd3.xml like this, and save it as cd4.xml:

This XML is formatted like this in IE5:

This way, the application could be coded such that if it only finds two <song> elements, but it finds a <songs> element which contains the text "11", it can deduce that there are 9 songs missing.

©1999 Wrox Press Limited, US and UK.