I have a new VB.NET project to work on. It's so innovative that I know I'll have to clearly document my code, just in case I'm hit by a beer truck on the way to work. But while I could comment my source code in-line, using the standard VB apostrophe comment character, I discovered uncomfortable limitations.

VB.NET doesn't have the same functionality for component commenting as does its sister language, C#. In C#, you can include predefined XML tags in your source code, and the Visual Studio IDE will make them readable in the Object Browser and in Intelli-sense. VB.NET does not do so, unless you use a third party tool.

In C#, XML inline comment tags appear in the Object Browser automatically.

That's not to say that you have no options at all. VB.NET lets you use XML comment pages, which you generate by selecting Generate Comment Pages... from the Tools menu. You'll end up with an HTML page that is visible from within your project. Yet, the document that it produces is somewhat limited for hardcore programming. The HTML comments page shows the class name with subordinate method and property names. Remarks and parameters descriptions are missing. This is not a lot of information to provide to those that use your component.

You use Generate Comment Pages to create HTML documents the classes that you make.

VBCommenter to the Rescue

I do a lot of component development, so it's a serious drawback for me to be unable to view my comment code in the Object Browser. Plus, because other programmers use my code, they need to understand what I'm up to; my colleagues need the ability to view class, property, and method comments outside the compiled source code.

Luckily, there's a free tool that provides the same component commenting capabilities for VB.NET as you'd have in C#. VBCommenter, produced by a .NET work group that Microsoft sponsors, is available as a free download, included in the Visual Studio Power Toys suite.

VBCommenter is easy to install and straightforward to use. I'll take you through a little demonstration of how to put it to work.

After you install the software in VS.Studio, the Tools menu gains an entry for VBCommenter.

When you install VBCommenter, the installation program adds the VBCommenter Option entry to the Tools menu automatically.

When you click VBCommenter Options, a dialog appears. This dialog allows you to set the generator characters. The default is three apostrophes (''').

You can configure VBCommenter to use characters other than apostrophe to generate comments in XML.

Working with VBCommenter

To generate XML Comment code, you place your cursor above the property, method, or class definition and strike the comment characters. VBCommenter generates the XML code template for the given item automatically. Also, the add-in is smart enough to inspect your code to generate the XML tags for parameters and return values.

VBCommenter generates specific XML comment templates for class, method, and property code. Each looks slightly different.

Now that you have the structure for your comments, you need to fill in the template with your entertaining—and presumably relevant—prose, in between the relevant XML tags. The comments that you add to the XML code template appear as entries in the lower window of the Object Browsers when you view your component.

The XML tags that VBCommenter generates creates comments viewable in the Object Browser after you build your component.

The Gotchas

VBCommenter is a good tool, but it is not perfect. Frankly, it is buggy. Expect to get null pointer errors, every so often; an annoying message box appears, informing you of some mysterious internal null pointer error. In my experience, the code and existing comments are not affected at all and there is no system crash, but it doesn't leave me in a good mood.

It also isn't an exact replacement for the functionality built into VS.Studio for C# programmers. VS.Studio lets you view the XML comments of a current C# component project in the Object Browser as you work on that project; VBCommenter does not. You must compile the VB.NET project first, before you can access the VB.NET component from a test container project.

This may not be a problem for long, which might explain the reluctance to fix the software's defects. Microsoft has said it'll add more XML commenting features to Visual Studio 2005. Thus, tools such as VBCommenter will become obsolete once the product comes out. Yet for today, the tool will make working with your code easier, not harder.

And, of course, VBCommenter will be useful only if you use it. Commenting code is like flossing teeth. You know you should do it. You know that you'll be the better for it. But, as you're running late for work, you think it is something that you can do extra hard tomorrow. Then, one day, you wake up in pain and the dentist tells you that you'll need to spend a kazillion dollars to make our teeth healthy again... if only you had flossed.... Commenting code is not something that you do to make you code better today. It is something to make your code better tomorrow.