C# Documentation (It ain’t that hard)

Jason Pearl, Thursday, October 15, 2009 @ 12:14 pm

On a recent project after months and months and hundreds of files worth of work, we were asked to provide documentation for the code. This request could have gone one of two ways depending upon how well we adhered to some basic documentation rules.

The C# compiler itself is setup to extract documentation which can then be piped through one of a number of documentation generation apps. My preference is a new(ish) project called SandCastle from Microsoft, which aims to provide much of the featureset that NDoc once did. Unfortunately this application provides no GUI. A fine gentleman named Eric Woodruff stepped in to wrap this application in an easy to use GUI for us aptly named Sandcastle Help File Builder. Through the use of good comments written WHILE we wrote the code, we were able to pop out some documentation for every bit of code we wrote in a matter of minutes. Add to this the nice information we get when using our code via intellisense, and it simply doesn't make sense not to strictly enforce documentation standards on your project.

I often see code written with little or no attention paid to comments. Sometimes the comments are fairly haphazard and appear to follow no standards whatsoever. By following documentation standards, you too can auto generate documentation instead of wasting hours or days going back through and trying to remember what your code does. The following are some of the more important tags available for C# documentation, presented in a roughly organized fashion. You can find a more complete list here.

Method/Type Description:
summary - To describe a type or type member
param name='name' - To describe a parameter of a method
example - To show an example of code usage
returns - To describe the data to be returned from the method

Formatting:
code - Denotes what is contained is code
c - Similar to 'code' but used within comments
para - Usually nested in another tag, allows formatted text

References:
see cref='member' - To specify a link to another type
seealso cref='member' - To specify text that may appear in a "See Also section" (I honestly have no clue what that means)
paramref name='name' - To reference a parameter in comments

There are other tags available, but with these in your arsenal, you should be able to build some nice documentation. Here's an example of what I would consider well commented code:

/// <summary>
/// This is a class description
/// </summary>
public class MyClass
{
  /// <summary>
  /// This method gets something
  /// </summary>
  ///
<param name="number">An integer input</param>
  /// <returns>Returns a <see cref="string"> based on the provided
  /// number
  /// </returns>
  public string GetSomething(int number)
  {
    ...
  }
 

That's not that painful is it?

Related posts:

1. Agile Development, Documentation and Bringing Projects back from the Dead
2. Integrating Design and Agile Development
3. ZK – Documentation & Tools
4. Writing Agile Requirements
5. One Way to Organize the Documentation for Wikis and Trackers in Agile

Comments (1)

Software Development

Comments: 1 so far

• Leave a comment
• Comment feed for this post
• TrackBack URL

1. 

   So would you say that these are the main forms of comments in the code that you need? i.e. inline comments are much less important (”int foo; // counter of foos”, “/* Sort through the list and find the highest item */”).

   Would perhaps a nice rule of thumb be to ensure you use the form of comments you mentioned for all classes and methods, and supplement that with the odd inline comment if needed to explain the functional intent of more complex sections of the code?

   Comment by Greg L, Friday, October 16, 2009 @ 12:18 am

Leave a comment