Claudio Lassala's Blog

Here at EPS we’ve been getting more and more serious about the use of XML comments. Users of our framework always appreciate when we have good XML comments and always ask us to keep improving on it, so as much as possible we’re going back to legacy code and improving comments, as well as trying to write good comments for any new code we write.

Fortunately, there are tools to help us improve the quality of our XML comments. I’m listing here some of the ones we’ve been using.

Visual Studio

The code editor supports adding XML comments by typing /// (or ”’ in VB) right by the Type or member you want to put comments on. We can then set a property on the project (on the Build tab) to specify that an XML file has to be created with all the XML comments content upon every build. By default that option is unchecked.

We use different build configurations here, so we only turn that option on in our "Check-in Build", which is our most restrictive build. That option is off in all other builds because we want the local build process to be as quick as possible (if we’re in TDD-mode, we don’t want the compiler busy generating XML documentation files unnecessarily…).

When "XML documentation file" is enabled on the current type of build configuration for the project, the compiler lists warnings for every public type or member that does not have XML comments on it. In our check-in build we enable "Treat Warnings as Errors", which prevents the developer from even building the binaries in case there are missing comments.

Unfortunately, the compiler does not check whether there is actually anything within the XML comment tags, so a developer could get around the compiler error with something like this:

That leads me to the next session…

Custom Rules for FxCop and Code Analysis

In order to make sure "smarty-pants" developers are aren’t fooling the compiler just by putting in empty comments, we wrote a custom FXCop rule that traps that, so that such violation won’t go unnoticed.

Not only we want developers to put comments on public members, but we also want them to put comments on private members. While the comments on the public members are helpful for people using the APIs, the comments on the private members are helpful for people maintain the code within the APIs.

Since the compiler only catches missing XML on public members, we also made our custom FXCop rule check for comments on private members.

Of course, those rules are no good if the assembly is not set to create the XML documentation file, so we also use a rule that checks to make sure every assembly has the xml file. We borrowed the rule from this article.

Why document private members??

The other day I was going through some code I found on the web (some very good code, by the way. I’ll be writing another post about it soon), and ran across this notFiredResult field somewhere. The usage or reason of this field wasn’t entirely clear to me, and IntelliSense didn’t give me much:

I then pressed F12 (or Go to Definition), and got to the field’s declaration:

Ok, that tells me something that’s more useful. I just wrapped up the existing comment into an actual valid XML-style comment, like so:

And now I get that directly in IntelliSense:

That’s such a simple change, but the removal of friction helps a lot when working on the code (the less I have to jump around the quicker it is for me to get the job done).

GhostDoc

This is one of the best free add-ins for Visual Studio: GhostDoc. This is a must-have tool to our developers here. 

GhostDoc does a pretty good job at creating initial XML comments. However, developers should ALWAYS make sure to verify what GhostDoc created, and edit it accordingly. For instance, if a method is named "MyMethod", GhostDoc creates documentation that say "Mies the method." (of course nobody should name a method like that anyways, but the point is that there are cases where GhostDoc can’t quite figure out the best way to write the comments, so the developer should always do some proof-reading).

Also, one feature I love bout GhostDoc is that it "inherits" XML comments from baseclasses and interfaces (when available). Say you override a method from a baseclass in .NET; you don’t have to type in the comment yourself, since GhostDoc will just grab the comments from the baseclass and paste it into your code.

Documentor

CR_Documentor is another plug-in for Visual Studio that rocks! When the Documentor window is being shown, it displays a preview of what the MSDN-like type of documentation will look like once you turn XML documentation into and more human-readable documentation. This helps a lot when typing the XML comments, since the developer can immediately see what the output is going to look like.

Even if you’re not planning to create the MSDN-like documentation out of your source code, the tool is also useful to improve the visualization of the XML comments within VS; a formatted HTML page is much easier to read then green comments in XML tags. Whenever I’m working with some code that I’m trying to learn about it, I have the Documentor window docked somewhere in VS:

Also make sure to check what’s available when you right-click on an XML comment once you get Documentor installed. There’s a bunch of little things that helps a lot composing decent documentation (such as options to add bulleted lists, sample source code, etc.):