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 am looking for a recommendation of a best practice for XML comments in C#. When you create a property, it seems like that the expected XML documentation has the following form:

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

But since the signature of the property already tells you what operations are available to the external clients of the class (in this case it is both get and set) I feel like the comments are too chatty and that perhaps the following would be sufficient:

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft uses the first form so it seems like it is an implied convention. But I think that the second one is better for the reasons I stated.

I understand that this quetion is an adept for being marked as not being constructive, but the amount of properties that one has to comment is huge and so I believe that this question has its right to be here.

I will appreciate any ideas or links to official recommended practices.

share|improve this question
    
honestly the only thing the comment gives me that isn't in the code (assuming this is a member of User) is that the id is unique. so none of it is 'necessary'. –  jk. Mar 28 '13 at 12:49
    
@Tomas - have you installed the GhostDoc plugin? it will generate good XML comments for you if you use good property names to start with and automatically put the gets or sets or gets depending on the property accessors. –  Trevor Pilley Mar 28 '13 at 15:21
    
@Trevor - I do have it installed. I was just thinking whether I should change its templates and remove the "Gets or sets" or not :). It is a great plugin though. –  Tomas Mar 29 '13 at 7:18

4 Answers 4

up vote 26 down vote accepted

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 enter image description here 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

share|improve this answer
    
Thanks for a thorough answer. I think that these are unfortunately limitations of the Visual Studio IDE. I have thought about it and I think that the intellisense could show you which properties are, e.g., get-only in the current context. It is not very convenient to bend the documentation to fit a particular development environment. Still I think that Visual Studio and C# are so closely related that this just might be the right solution. –  Tomas Mar 28 '13 at 13:38
1  
@Tomas I agree that Visual Studio should make more of a distinction. It certainly is happy to give me a red squiggly line the second I use the property improperly. –  Mike Mar 28 '13 at 13:41

The only time I add information about the getting and setting of a property in the XML comments is when it doesn't behave as expected (straight public get and set).

If either are private or if they contain additional logic then I mention them, otherwise I just document the intent of the property.

share|improve this answer

StyleCop uses the Gets or Sets ... notation which it enforces with rule SA1623.

The linked page lists another case you haven't listed:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

The other option you list would be.

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

vs

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

Which wouldn't provide information on the Intellisense hint that the property is read only, you could come up with a convention for this case too, but Gets ..., Gets or Sets... does the job nicely imo.

There are also other varients listed on the StyleCop rule which are clear by using the Gets or Sets... but might not be without.

Also when generating documentation from something like Doxygen or Sandcastle the full notation would document the API (for example) better.

share|improve this answer

I'd be happier with the more verbose version.

The other is like having a comment of "increment counter" after, well, incrementing a counter variable.

It is obvious there is a Get and Set. If you had a private setter, it'd be obvious as you would have the private keyword.

Comments should add value, not just be comment version of what the code actually is.

share|improve this answer

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.