Code Tips & Tricks 1: GhostDoc & NDoc

Documentation is the coders best and worst friend.  It is a two sided sword, it makes your life easier but no one likes writing it.  So coders do what we do best and find a way to make the computer do it for us. There are two tools which I use on a regular basis when I’m working on a project.  while these tools do not work perfectly they do cut down the amount of work it takes to get good project documentation.

The first step and probably the most useful to a coder is XML comments.  These are the comments above a method that are used to generate the handy intelisense comments.  One of the first code practices I believe you should implement is providing XML comments for every method and class.  I know you’re saying great that just doubles my work load but not quite. Roland Weigelt has come to the rescue by creating a tool he calls GhostDoc.  GhostDoc is a plug in for Visual Studio that generates XML comments for you.  It uses some basic configurable rules to determine what the comment should be.  If you have a standard naming scheme for your methods and classes you can create rules to generate the comments you want.  I’d like to take a disclaimer here and say you should not just download GhostDoc and comment everything with the default comments.  While it works good it does not work great and sometimes requires some editing, however, you can eliminate most of this by creating custom rules.

   1:  /// <summary>

   2:  /// Gets the ghost doc URL.

   3:  /// </summary>

   4:  /// <param name="peram1">The peram1.</param>

   5:  /// <returns>URL to download GhostDoc</returns>

   6:  public string GetGhostDocURL(int peram1)

   7:  {

   8:      return @"http://www.roland-weigelt.de/ghostdoc/legalStuff.htm";

   9:  }

The next tool came in very handy when I was still in school and I was required to create documentation for every project that I did.  I have always used XML comments because I often reuse libraries and I hated going back to figure out what a method I had written 2 years earlier did. The tool that will save you time when creating documentation is NDoc.  It is an open source project that looks at your XML comments in your code and creates .cfm help files as well as MSDN styled web pages.  The styles can be customized to fit your companies page or to simply put you logo in the corner.  This is by no means a be all end all of documentation generation but it gives you a good boiler plate. NDoc can be downloading here.

The use of these two tools should make the documentation process a  little less painful for you and if not you can always hire an intern to do it for you.