Question

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?

Answer 1

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!