C# XML Comments – Tools of the Trade

A few months back, someone at work commented on the amount of XML comments in my C# code. I admit, I do tend to prefer more comments in my C# code. Unless I’m working on the quickest and dirtiest of throw-away apps, I try to comment my classes as if they were going to be used as a framework by other developers. I find that the process of creating the documentation actually helps me focus on what the class or method should actually be doing.

Also, I’ve been on the receiving end of poorly documented code.

To be clear, I’m not talking about comments in the body of a method itself. I’ve found that if the body of a method requires more than a few comments to describe what it’s doing, that method probably needs to be refactored. I’m talking specifically about the XML comments (or JavaDoc comments in the case of Java source code) of the public and protected members of my non-private classes.

This post describes the tools I use on a regular basis to produce good code documentation. These tools are primarily targeted towards C# developers working in Visual Studio. I may do another post later to describe tools useful for recreating this process in other languages and platforms. If you’re a VB.NET programmer, there’s a good MSDN article on XML comments in Visual Basic you might want to check out.

GhostDoc

GhostDoc is a free Visual Studio add-in originally created by Roland Weigelt. It was recently acquired by SubMain, but they’ve stated that it is their intention to keep it free.

Visual Studio 2008 already helps a little with XML documentation by inserting the tags for you when you type three forward slashes (i.e. ///) and hit Enter.

[csharp]
/// <summary>
///
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
public string GetName(int id)
{
return string.Empty;
}
[/csharp]

GhostDoc does you one better by filling out the empty XML comment tags with text based on code element type, parameters, name, and other contextual information. The default keyboard shortcut is Ctrl-Shift-D. You can also get at GhostDoc via the context menu.

[csharp]
/// <summary>
/// Gets the name.
/// </summary>
/// <param name="id">The id.</param>
/// <returns></returns>
public string GetName(int id)
{
return string.Empty;
}
[/csharp]

Usually, a bit of modification to the comments generated by GhostDoc is all I need.

Agent Smith

Agent Smith is a C# coding style validation plug-in for ReSharper hosted on Google Code. You need to have ReSharper installed in order to use it. In addition to naming validation and smart paste, Agent Smith provides some valuable features for writing XML commenting including comment validation, re-flow, and spell check.

I use this plug-in primarily for pestering me about naming conventions and for the the spell checking. I’ve tried other Visual Studio plug-ins for spell checking, but by far this is the one I like the best.