Seven Steps to Quality Code – Step 2

XML Comments and GhostDoc

This is step 2 in a series of articles, starting with Seven Steps To Quality Code – Introduction.

The next step on our journey towards quality code involves the introduction of our first tool, GhostDoc, which is an essential tool if you want your code to be documented/commented correctly.

If your code is to be easily maintainable in the future, by the author or by someone else, it is critical that it is documented in a way that allows anyone reading or using the code to determine what a method or property is used for.  We are all used to the .Net Framework code providing us with information via intellisense about a class member (i.e a method or property) and we should expect no less from our own code.  Using XML comments allows us to satisfy both these requirements.

So how do we do this?  Simply, when we create a method or property we add some standard XML tags immediately before the declaration, like this:

/// <summary>
/// Checks that the customer name is valid. 
/// </summary>
/// <param name="name">The name to check.</param>
/// <returns>Returns true if the name is valid, false otherwise.</returns>
public bool CheckNameIsValid(string name)
{
    return (!string.IsNullOrEmpty(name)
        && name.Length > 1);
}

Visual Studio helps us out by providing a blank template if we type 3 forward slashes on the line above the method declaration. Once comments have been created in this way, they will be associated with the method and displayed in Intellisense, making developing the software a whole lot more productive.

Providing this feature takes a little effort, but this effort is paid back almost immediately.  The very next time you want to use the methods you have documented, information on what they do and the parameters required is available at your fingertips.

To make things even better, download a copy of GhostDoc and get lots of the work done for you!

This tool will actually create a significant amount of the documentation for you.  Simply position your cursor on the element that you want documented, press the magic keys (CTRL + SHIFT + D by default) and GhostDoc will attempt to create your XML comments.  It does this in a number of different ways, such as:

  1. If your element is an override, it will take the XML comments from the overridden element on the base class.
  2. If your element is part of an interface implementation, it will take the XML comment from the appropriate interface member.
  3. For a constructor, a standard comment, including a reference to the class will be created.
  4. For properties, GhostDoc will determine whether the property is read/write, read only or write only and generate a comment that starts with “Gets or sets…”, “Gets…” or “Sets…” as appropriate.
  5. It looks at property types and uses language processing algorithms to do clever things like determine that an appropriate comment for a boolean property called is “IsValid” would be “Gets or sets a value indicating whether this instance is valid.”
  6. Method names are also parsed using the same algorithms to produce method summaries.  For example, a method called “SaveCustomer” will get a comment of “Saves the customer.”
  7. If it cannot determine appropriate comments, then a blank template is generated in the same way as if three slashes had been entered.

This tool is fantastic, but you do have to put some effort into it too!  The sharp eyed amongst you will have noticed that if a bit of software can use language rules to “understand” what a method or property does, then developers reading the code can do the same and so the comments are a little bit pointless.

To some extent, this is true and it is often necessary to improve the comments produced by GhostDoc in order to provide useful information beyond what can be determined simply from the method or property name.  This doesn’t detract from the usefulness of the tool, however, which makes the job of documenting your code so much easier.

In step 4, we’ll see why you simply won’t be able to live without GhostDoc!

Next though, it’s step 3, where we start to see just how many bugs there are in our code!

Leave a Reply

Your email address will not be published. Required fields are marked *