What Are Best Practices For Documenting C# code with XML comments?

Question

I'm going through some new code I just wrote and adding NDoc sytle comments to my classes and methods. I'm hoping to generate a pretty good MSDN style document for reference.

In general, what are some good guidelines when writing comments for a class and for a method? What should the NDoc comments say? What should they not say?

I find myself looking at what the .NET framework comments say, but that gets old fast; if I could have some good rules to guide myself, I could finish my docs a lot faster.

Answer 1

If you end up with comments that don't add any value, they're just wasteful.

For example

/// <summary>
/// Get's manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

...you added absolutely no value and just added more code to maintain.

To often code is littered with these superfluous comments.

Answer 2

For properties, your comment should indicate whether the property is read only, write only or read write. If you look at all official MS documentation, property doc comments always start with "Gets ...", "Gets or sets..." and (very rarely, avoid write only properties usually) "Sets ..."

Answer 3

As stated on the MSDN page, you use XML documentation comments to generate documentation automatically, so it makers sense if you're writing an API and don't want to work twice at both code and documentation, with the added benefit of keeping them in sync - every time you change the code, you modify the appropriate comments and regenerate the docs.

Compile with /doc and the compiler will search for all XML tags in the source code and create an XML documentation file, then use a tool such as Sandcastle to generate the full docs.

Answer 4

One thing about comments is UPDATING them. Too many people alter a function then don't change the comment to reflect the change.

Answer 5

In comments used to build API documentation, you should:

• Explain what the method or property does, why it exists at all, and explain any domain concepts that are not self-evident to the average consumer of your code.

• List all preconditions for your parameters (cannot be null, must be within a certain range, etc.)

• List any postconditions that could influence how callers deal with return values.

• List any exceptions the method may throw (and under what circumstances).

• If similar methods exist, explain the differences between them.

• Call attention to anything unexpected (such as modifying global state).

• Enumerate any side-effects, if there are any.

Answer 6

StyleCop provides hints for code and commenting style. The suggestions it gives are in line with the MSDN documentation style.

As for the contents of the comment, it should give the user of your code enough information on what kind of behavior to expect. It should also answer potential questions the user might have. So try to use your code as someone who doesn't know anything about the code, or even better, ask someone else to do so.

Answer 7

I write the <summary> comment to include the information I would want to know if I was the one calling that function (or instantiating that class).

I write the <remarks> comment to include information I would want to know if I was tasked with debugging or enhancing that function or class. Note: this doesn't replace the need for good inline comments. But sometimes a general overview of the inner workings of the function/class are very helpful.

Answer 8

Don't forget what's a valid XML is. For example:

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(Error: invalid XML).

Answer 9

I've written a blog post about it: http://blog.gauffin.org/2010/06/my-name-is-more-docu-more/