Good Practices for Method Summary XML Comments

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

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.