C# Documentation (It ain’t that hard)

This post was previously on the Pathfinder Software site. Pathfinder Software changed its name to Orthogonal in 2016. Read more.

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 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:

/// 

/// This is a class description
///

public class MyClass { ///

  /// This method gets something
  ///

///An integer input /// Returns a based on the provided /// number /// public string GetSomething(int number) { … }

That’s not that painful, is it?