XML Documentation – What to Include in Comments

ccoding-style

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?

Best Answer

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.

Related Solutions

C# – What to Include in Class Documentation Header

Most of the information you've suggested there would be found in the source repository.

The only thing you really need is the purpose section, which says what the class is there for.

Would it be tedious to look in repository every time you want to know the other information? I'd say no. How often do you care who the original author was? Or when the file was first created? Plugins (such as Ankh SVN for Visual Studio) often allow you to right click within your current file and view the repoistory log for the file, so it's not that much of a hassle to actually see this information.

Additionally, if you store the version history in a comment, this comment needs to be maintained. So over time there's a chance it could be lying to you. The source code repository automatically keeps this historical data, so doesn't need that maintenance, and will be accurate.

C# Documentation – Is ‘Gets or Sets’ Necessary in XML Documentation?

The signature may tell other pieces of code what operations are available; however, they are not clearly shown to the coder as he or she is working and XML documentation is meant for people to consume and not a compiler.

Take this class for example:

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

When intellisense is pulled up to access one of these properties there is no indication which ones can be written to, read from, or both:

enter image description here

Likewise when viewing the documentation we also aren't quite sure:

enter image description here

As such we add the gets or sets, gets, or sets to make it easier on the programmer while writing the code. It certainly would not be write a large block of code that reads and processes some data only to find out that you cannot write that data back to the property as expected.

enter image description here

Related Topic