Good practice for summarizing XML methods Comments

Question

Recently, I have been using generalized XML method comments at the top of my procedures, and I am wondering if there are any logical or good methods associated with this.

I never put anything in the notes, because I put the description of the method in the final tag. What is included in the resume and what belongs to the notes?

I rarely put anything in the return tag because it seems like it will be superfluous, as I usually explain what is returned in the resume. Should I just keep the type of the object returned in the return tag?

Can anyone advise a good, logical, or generally accepted approach for these XML comments, which would be useful for other programmers on the team without requiring the same information to be displayed multiple times?

Answer 1

In my opinion, you are right that <summary> is probably the tag that you will use most often to explain what your method should do. But if your methods have good, useful names, then expect most developers to use this to make some assumptions about how this 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 this in mind, instead of writing paragraphs about what this method should do, I try to focus my comments on any “received” that I know about, knowing that if someone uses my code and it doesn’t work how they think they need it, the first thing they will do is look at the documentation, hoping for some kind of guidance. Below are a few examples of how I used various tags.

• <returns> - Indicate that the return value may be null. Describe the semantic difference between null vs. return string.Empty
  
• <remarks> - great for explaining "gotcha" s, for example. "The reader must be in a ready state, and the cursor is in the right position to start reading. The caller is responsible for closing the reader after this method is completed." I usually add these comments as necessary after a fuss with the API for half an hour before I realize some silly details that were not obvious.
  
• <example> - Good APIs should be easy to use, but sometimes you cannot help them. This is great for providing guidance on how the method should be used (although you cannot guarantee that it will be used). See the 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 that I could come up with, but I hope this helps you point in the right direction!

Answer 2

Tags that I use the most:

• <summary> - assignment of a method / class / member with the tag <see>
• <param name="paramName"> - what is the parameter for
• <returns> - what the method returns
• <see cref="referenceToMember"/> - allows you to refer to another class / member (great for use in constructors)
• <exception cref="referenceToMember"/> - reference to the exception raised by the method
• <example> <code>... - If you want to give an example of using the method
• <value> - describes the value of the property
• <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 } 

Auto Tag Creation

Instead of manually inserting these tags, you can also use free visual studio add-ons such as the Ghost Doc to create the necessary tags.

Using xml tags

In addition to providing information in the API (or the developer reference document), it allows the user of this element to receive important information, such as exception types, that the method can use. I am quoting this example because it is very useful to know which exception types can be selected by helper / model classes. The view / controller class can catch only those types of exceptions and handle them.

Answer 3

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

if you are writing a method that can be used by a small command, or if you are creating a class library or API for a widely used application, they do not have the same commenting requirement.

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

Answer 4

Breaking information about your class members into the correct parts (summary, return, parameter, exception) allows other tools, such as the object browser, intellisense, class, etc. work better.

I would suggest (not to say that this is "best practice", but it works for me):

 <summary/> - tell me what the member 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 advantage is breaking up the information into smaller parts, rather than reducing everything to a summary, is that you can use all the tools built around the xml documentation.