The Best Way to Add Reference Comments to Your XML Code

Get the facts with this step-by-step guide

Woman's hand working with laptop in office
Guido Mieth/Moment/Getty Images

If you're interested in adding reference comments to your XML code, use this step-by-step tutorial for guidance. You can learn how to execute this function in just five minutes. While the process is easy to complete, you should still know some basics about XML comments and their usefulness before you begin.

Why XML Comments Are Useful

Comments in XML are nearly identical to comments in HTML, as they both have the same syntax.

 Using comments allows you to understand code you wrote years before. It can also help another developer who's reviewing the code you developed understand what you wrote. In short, these comments provide context for code. 

With comments, you can easily leave a note or temporarily remove part of an XML code. Even though XML is designed to be "self-describing data," on occasion you may need to leave an XML comment.  

Getting Started

Comment tags are comprised of two parts: the part starting the comment and the part ending it. To start, add the first part of the comment tag <!-- Then write whatever comment you would like. Just make sure you don't nest comments within other comments (see tips for more details).

After that, you'll close the comment tag -->

Useful Tips

When adding reference comments to your XML code, remember that they cannot come at the very top of your document. In XML, only the XML declaration can come first:​

<?xml version="1.0"?>

As mentioned above, comments may not be nested one inside another. You must close your first comment before you open a second. Also, comments cannot occur within tags, e.g. <tag ></tag>.

Never use the two dashes (--) anywhere but at the beginning and end of your comments. Anything in comments is effectively invisible to the XML parser, so be very careful that what remains is still valid and well-formed.

Wrapping Up

If you still have questions about adding reference comments to XML code, you might want to read a book to give you a detailed picture of how the process works. Books such as C# 5.0 Programmer's Reference by Rod Stephens may prove helpful. Check online retailers or your local library for similar books.