Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

migrated from stackoverflow.com Sep 15 '11 at 7:22

This question came from our site for professional and enthusiast programmers.

5  
"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 –  Ed S. Sep 13 '11 at 22:26
3  
100% coverage doesn't apply to private methods, especially event handlers. –  SLaks Sep 13 '11 at 22:28
1  
GhostDoc writes my documentation for me. "What does GetData() do" you ask? Why, it Gets the data of course! –  Justin Satyr Sep 13 '11 at 22:28
    
@Slaks: Ok then, that makes sense. I didn't know that "100% coverage" implied only public methods, types, properties, etc. –  Ed S. Sep 13 '11 at 22:29
2  
@Justin: GhostDoc looks pretty cool. I might pick it up. –  mbmcavoy Sep 13 '11 at 23:00

3 Answers 3

up vote 6 down vote accepted

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.

share|improve this answer

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)

share|improve this answer

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.

share|improve this answer
    
Depends. What if you have a public get but an internal set as a property? How do you comment it? :-) –  Guillaume Nov 7 '12 at 8:28
    
@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 Nov 7 '12 at 10:23

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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