Taking the pain out of code documentation

I have never known a developer that liked writing document let alone writing code document, well I take that back there was one guy but he had *Issues* and we’ll just leave it at that. I have heard all of the excuses, and in the end it still comes down to, we would rather write code then write about the code.

One common statement coming from the TDD/DDD methodologies is that the unit tests document the code; while this is great if we have the unit test, but even then a little documentation would still be useful so we don’t have to dig though unit test to figure out how to use a library. Another favorite excuse is the method names document themselves, granted having intelligently named methods and variables make understanding the code a lot easier(and we’ll get into that latter) but short of having the average method name be 40+ chars long this really isn’t practical either.

Luckily the are some tools to make writing code documentation much easier. For starters the .NET compiler can be configured to generate XML documentation files by setting an xml output file in the project build configuration. The xml content is created from specially formatted XML comments that looks like this

   1: /// <summary>

   2: /// Saves the contact.

   3: /// </summary>

   4: /// <param name="contact">The contact to be saved.</param>

   5: /// <returns>

   6: /// A true or false result of the successful saving this contact

   7: /// </returns>

   8: public bool SaveContact(Contact contact)

You can write this by hand or use a tool like the GhostDoc plug-in for Visual Studio. GhostDoc will auto generate documentation based on configurable rules for the different objects, classes, method, properties, etc. One of the very nice features about being able to configure the documentation rules is you can add additional item like remarks that say when it was documented and by who.

The second nice thing about using GhostDoc is the rules used to figure out what to put into the documentation can be used to make sure your using intelligent names, it’s not always right but it can be a good indicator for how good of names your using.

So why add this? This gives you two advantages, first it adds intelligence for your code, next it allows you to create MSDN like documentation using the .NET documentation generator Sandcastle.

Sandcastle can be downloaded from http://sandcastle.codeplex.com/ and provides a command-line interface for building your documentation from the .dll and .XML file generated by the .net compiler making it easy to add documentation generation to your automated build system. For the user it’s a little clunky and painful to use, if you want to build the documentation without scripting, there is an app for that, the Sandcastle Help File Builder located at http://www.codeplex.com/SHFB.

Basically this lets you build a configuration that can include what is documented, the layout of the documentation, adding headers, footers, errors for missing items etc. and when you’re all said and done you get documentation that looks like this

it’s that easy.