I'm trying to make a point of documenting my code better, especially when it comes to the XML comments on class members, but often it just feels silly.

In the case of event handlers, the naming convention and parameters are standard and clear:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
    // actual code here...

I also frequently have simple properties that are (IMO) named clearly so that the summary is redundant:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

I don't feel like such comments don't add any information that the declaration itself doesn't already convey. The general wisdom seems to be that a comment that repeats the code is best left unwritten.

Obviously, XML documentation is more than just regular inline code comments, and ideally will have 100% coverage. What should I be writing in such cases? If these examples are OK, what value do they add that I may not be appreciating now?

  • 6
    "and ideally will have 100% coverage" - That's very debatable. I like them for a type's public interface solely for intellisense popups, but for private methods they are simply too verbose IMO Commented Sep 13, 2011 at 22:26
  • 3
    100% coverage doesn't apply to private methods, especially event handlers.
    – SLaks
    Commented Sep 13, 2011 at 22:28
  • 1
    GhostDoc writes my documentation for me. "What does GetData() do" you ask? Why, it Gets the data of course! Commented Sep 13, 2011 at 22:28
  • 2
    @Justin: GhostDoc looks pretty cool. I might pick it up.
    – mbmcavoy
    Commented Sep 13, 2011 at 23:00
  • 1
    @Justin: arg, I hate GhostDoc - it seems brilliant at first but after a while you realise that you can spot the auto-generated comments a mile off, usually when you come back old code and have to figure out what it does. While it does make it very easy to XML comment everything it doesn't ensure that those comments have any actual information in them. GhostDoc gives you a good starting point, but makes it very easy to be lazy and leave out anything that you couldn't have figured out by glancing at the name and signature.
    – Keith
    Commented Sep 15, 2011 at 7:51

3 Answers 3


XML doc comments are intended for public members.

The compiler warning clearly states this:

Missing XML comment for publicly visible type or member 'Type_or_Member'

You should only add XML comments to private members if those members aren't already obvious from their names.


Pure opinion here, so take it for what it's worth.

I hate superfluous xml comments. Doubly so for the ghost doc style ones that simply add spaces to the method/property name. It adds no value and simply clutters my view of the actual code.

If something needs clarification, by all means, comment it. However, a lot of clarity can be conveyed by small focused methods with meaningful names. Don't comment code if you can improve it and make the comment unnecessary.

Don't even get me started on the unnecessary use of this. and Me..

As a side note, I would love to have a Visual Studio addin that let me toggle the visibility of xml comments. (hint, hint)

  • I would guess that the this. thing may have gotten started because for some reason Microsoft's official guidelines recommended using the exact same naming convention for local variables and instance private variables. That is a terribly flawed style, IMO -- in some cases you are one fat finger away from a StackOverflowException in property sets or MyProperty = MyProperty; causing a field to be initialized to zero instead of a constructor parameter, and even Microsoft continued to use m_ internally most of the time.
    – jrh
    Commented Jan 17, 2018 at 15:01

On a public member XML documents should be fairly verbose and complete, as @SLaks has mentioned.

However they can be really useful on private, protected or internal members too because Visual Studio will populate intellisense and help tooltips with the XML doc comments.

This means that:

// describe what this does
private void DoSomething() 
    // or describe it here...

Might be perfectly sufficient documentation, but:

/// <summary>describe what this does</summary>
private void DoSomething() 

Will be much easier to see quickly from elsewhere in your code.

Generally on public XML comments I'm writing for some external user of the API, and on internal XML comments I'm writing for me or others on my team.

Skipping parameter descriptions is probably a bad idea for the former and fine for the latter.

I would add (in public API docs especially) always include whether get or set on properties:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
    get { return SelectedItem != null; } 

It's not obvious from C#'s intellisense whether get or set are available, but putting it on the XML comment will mean you can tell at a glance from the tooltip.

  • Depends. What if you have a public get but an internal set as a property? How do you comment it? :-)
    – Guillaume
    Commented Nov 7, 2012 at 8:28
  • 1
    @Guillaume since the XML comments are public I'd go with just documenting the get in XML and document the set with regular // comments.
    – Keith
    Commented Nov 7, 2012 at 10:23

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.