CODEWITHSUNDEEP
.netasp.netvb.net
NoAlias
NoAlias

Reputation: 9193

Good Practices for Method Summary XML Comments

I have been using the method summary XML Comments at the top of my procedures lately and am wondering if there are any logical or good practices related to this.

I never put anything in the remarks because I put the description of the method in the summary tag. What belongs in the summary and what belongs in remarks?

I seldom put anything in the returns tag because it seems like it would be redundant as I usually explain what is being returned in the summary. Should I simply keep the type of object returned in the returns tag?

Can anyone advise on a good, logical, or commonly used approach for these XML comments that would be beneficial to the other programmers on the the team while not requiring the same information being displayed multiple times?

Upvotes: 6

Views: 7777

Answers (4)

jeremyalan
jeremyalan

Reputation: 4786

In my opinion, you are correct that <summary> is probably the tag you will use most often to explain what exactly your method is meant to do. But if your methods have good, useful names, then expect that most developers will use that to make some assumptions about how the method should behave. For example, they assume that calling "GetName" probably has no side effects, and returns the name of the instance, regardless of what the comments say.

With that in mind, rather than writing paragraphs about what the method should be doing, I tend to focus my comments on any "gotcha"s that I am aware of, knowing that if someone uses my code, and it's not working the way they think it should, the first thing they will do is look at the documentation hoping for some guidance. Below are just a few examples of how I've used the various tags.

  • <returns> - Indicate that a return value may be null. Describe semantic difference between returning null vs. string.Empty
  • <remarks> - Great for explaining "gotcha"s, e.g. "The reader must be in a ready state, and the cursor positioned at the correct position to begin reading. The caller is responsible for closing the reader after this method completes." I usually add these comments as needed after fussing with an API for half an hour before realizing some silly detail that wasn't obvious.
  • <example> - Good APIs should be easy to use, but sometimes you can't help it. This is great for giving guidance on how the method was intended to be used (although you can't guarantee that's how it will be used). See example below.
<example>
var token = m_caller.GetAuthToken();
var result = m_caller.Call(method, token);
</example>

I'm sure there are hundreds of other examples I could dream up, but I hope that helps get you pointed in the right direction!

Upvotes: 7

Devendra D. Chavan
Devendra D. Chavan

Reputation: 9011

The tags that I use the most are:

  • <summary> - purpose of the method / class / member with <see> tag
  • <param name="paramName"> - what is the parameter for
  • <returns> - what does the method return
  • <see cref="referenceToMember"/> - allows to link to refer to another class / member (great for using in constructors)
  • <exception cref="referenceToMember"/> - reference of the exception being thrown by the method
  • <example> <code>... - If you want to give an example of the usage of the method
  • <value> - describes the property value
  • <c> - describes code segments (can be used with <returns>)

Examples

  • <summary> with <see cref=".."/> 

    /// <summary>
/// Initializes a new instance of the <see cref="Form1"/> class.
/// 
public Form1()
{
   InitializeComponent();
}

  • <returns> with <c>

    /// <summary>
/// Validates the date.
/// </summary>
/// <param name="date">The date.
/// <returns><c>true</c> if the date is valid; otherwise <c>false</c>.</returns>
public bool validateDate(string date)
{
    // Do something
}

Automatic tag generation

Instead of trying to insert these tags manually, you can also use free visual studio addons like Ghost Doc to generate the required tags.

Use of xml tags

In addition to the providing information in the API (or developer help document), it allows the user of the member to get vital information like the exception types that a method can throw. I quote this example because it can very helpful to know what exception types can be thrown by the helper / model classes. The view / controller class can then catch only those kinds of exceptions and handle them.

Upvotes: 11

Paul Kearney - pk
Paul Kearney - pk

Reputation: 5533

Breaking the information about your class members into the correct parts (summary, returns, param, exception) allows other tools, like object browser, intellisense, class view, etc to work better.

I'd suggest (not saying this is a "best practice", but it works for me):

<summary/> - tell me what the member's purpose is. What responsibility does it perform?
<param/> - give me a description of the parameter. If you use <seealso>, future developers will get links to that documentation as well.
<returns/> - describe what is being returned
<exception/> - tell the developer what exceptions can be thrown by the method. This gives them the opportunity to catch specific exceptions if desired, rather than just System.Exception. I don't do this very much.

I think the biggest benefit of breaking the information into smaller pieces rather than putting it all into summary is that you get to leverage all of the tooling built around the xml documentation.

Upvotes: 1

Steve B
Steve B

Reputation: 37660

Keep in mind that this comments are used to help another developer to understand the use of the function.

if you are writing a method possibly used by a small team, or if you are building a class library or API for an application that is widely used do not have the same requirement of commenting.

I think there is no other rule than "keep comprehensible". If you actually want to be a bit more rigorous, take a look at the MS framework documentation as a model.

Upvotes: 1

Related Questions