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.

Solution 1

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.

Solution 2

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

For example

/// <summary>
/// Gets 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.

Too often code is littered with these superfluous comments.

Solution 3

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.

Solution 4

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

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

(Error: invalid XML).

Solution 5

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 ..."

View more solutions

Comments

[Eduardo Scoz]

Yes, I understand comments can provide no value. That's why I'm looking for guidelines on comments that DO provide value.

[Eduardo Scoz]

Great! Any ideas for methods and classes?

[Eduardo Scoz]

I undestand the benefits and the how of XML documentation. I need a little bit of help on what people actually find useful in these comments.

[Matt Greer]

In all honesty the only company that takes doc comments seriously is Microsoft :) I would just browse their comments and get a feel for how they do them. They definitely have standards on how comments should be formatted and what they should say. MS also does a good job of indicating what exceptions a method throws. Sadly, doc comments end up being used as a band aid to fix minor issues in the C# language IMO (like relying on a comment or compiler error to find out if a property is read only, that irks me)

[luvieere]

@Esteban Araya as I've said, proximity to the actual code you're documenting, allowing you to document changes on the spot, without needing to switch to another app and search for the appropriate place to modify.

[Joseph Ferris]

I think that is more an example of poor documentation, not an example of where it should not be used. Public methods should likely have additional documentation, such as expected exceptions, preconditions, etc. For example, what does that method do when action is null?

[Joseph Ferris]

True. We have remedied this in the past by making it a part of a standard code review checklist.

[Jesse C. Slicer]

I take doc comments seriously and I don't work for Microsoft. Between good documentation comments, GhostDoc and Sandcastle/Sandcastle Help File Builder, our core libraries have a website developers can go to for reference. I really dislike having to intuit usage of methods/properties by stepping through code rather than reading concise doc.

[Jesse C. Slicer]

I rather find StyleCop a handy reminding tool for when I've added/removed a parameter from a method and spaced on updating the <params> nodes. From what I remember from my last gig, R# did that too real-time.

[stinky472]

+1. I think the predominant focus on documentation should be for public interfaces, even more when generating external documentations (doxygen, NDoc, etc). Clients don't need to know every nook and cranny of your class. The implementation details don't need to be documented in this format; the predominant focus should be on the public interface, how it is used, the pre/post conditions, and other things Jeff pointed out.

[Francisco Aquino]

Another option: Resharper does that in the UI.

[Justin]

Although I agree with your on the topic of superfulous comments, superfulous documentation is a different matter. In some cases it may be that you simply have nothing extra to document and your xml doc string is just an echo of the method name, however I still add that docsctring - partly because it confirms that the method is as simple as it seems (rather than someone not bothering to document the method), but mostly because it just looks wrong if its missing.

[mikemanne]

I wish I could upvote this answer 100 times. I regard those comments the same as I would a UnitTest which was hardcoded to always succeed. You've successfully checked the "I have comments" (or "I have unit tests") box, but have utterly failed to make the code more maintainable, stable, or better in any way.

[EoRaptor013]

Certainly there should be consistent and effective documentation for the public interface, but if your job includes updating, modifying, or rewriting an existing code base, documentation of private and protected entities is very helpful.

[Sinjai]

But how do you style that? Where can I find a good example of clear, helpful XML comment documentation? That would be a good addition to this answer, I think.