Simplify Visual Basic 2005 With XML Comments

by Pete Mather

Writing comments to describe each part of our programs is something that everybody knows they're supposed to do, but most of us don't take as seriously as we should. Now, with Visual Basic 2005, there is a simple way to comment your code that hooks up with IntelliSense to increase your productivity and make your life easier.

Using the new XML comments feature not only lets you know what you were thinking when you wrote the classes, functions and subroutines in your code, but it provides a standard, machine-readable way to tell the Integrated Development Environment (IDE) about your code too. The IDE can then integrate your comments into the IntelliSense facility, which means you can be lazier in the future! You can easily go back and add XML comments to existing code, which will help you when you re-use that code.

Firstly, let's look at how you actually use XML comments. Say you're writing a function that counts donkeys by taking the number of legs and dividing by 4. The declaration would look something like this:
Public Function CountDonkeys(ByVal legs as Integer) as Integer
Now, put the cursor on the line immediately above the function declaration (make sure there's nothing else on the line) and type three apostrophes. As if by magic, the IDE will insert an XML comments skeleton for you to fill in. If it doesn't, you must have typed the apostrophes in the wrong place.

Now you should have something like this:
'''<summary>
'''
'''</summary>
'''<param name="legs"></param>
'''<returns></returns>
'''<remarks></remarks>
Public Function CountDonkeys(ByVal legs As Integer) As Integer

All you have to do is fill in the gaps. If you're not familiar with XML, don't worry, it's very simple. An XML element has a start tag and an end tag. For the summary of what your function does, the start tag is <summary> and the end tag is </summary>. Just type the comment in between the start and end tags. In the same way, insert your comments to describe the "legs" parameter in between the <param name="legs"> and </param> tags, and the same to comment on what the function returns and any remarks you think might help when you read the code.

You should end up with something like this:
'''<summary>
''' Counts donkeys by dividing the number of legs by 4
'''</summary>
'''<param name="legs">Total number of donkey legs</param>
'''<returns>Number of donkeys</returns>
'''<remarks>Created by Pete</remarks>
Public Function CountDonkeys(ByVal legs As Integer) As Integer

Now, when you use that function in your code, the IntelliSense will be able to help you out by displaying your comments, as shown below:

IntelliSense shows summary comment as tooltip

IntelliSense shows legs parameter description as tooltip

That means you won't have to trawl through the code to find out exactly what a function does, or what it expects as an input. If you later add another parameter to a function, you can add a new comment in the XML comments block. Start by inserting a new line into the XML block. IntelliSense should automatically put three apostrophes at the start of it, and when you start typing the new start tag with an angled bracket "<", IntelliSense will help you insert the parameter tags, as it knows the names of any new parameters you have added to the function. You can also use XML comments for classes and properties, just by typing three apostrophes above their declarations.

You should note that you can't type angled brackets (i.e. the lesser than and greater than signs, < and >) within the comment text itself as this would confuse the IDE into thinking that you were starting another tag. Instead, you have to type the XML code &lt; to give "<" (Lesser Than) and &gt; for ">" (Greater Than).

Not only do XML comments help you document a new class or function, but they also make your life a lot easier when you use those classes and functions in your code. To get an idea of what to write in your comments, look at the tooltips that IntelliSense shows you when you use .NET functions. XML comments give you the full benefit of IntelliSense for your user-defined functions, making it quicker and easier to get the job done. If you're using VB2005 or VB2005 Express, you can start right now.