Cheat Sheet: Best practices for writing XML documentation in C#

The XML documentation tags of C# are described very well in the MSDN. However, the article does not explain how the contained phrases and sentences should be written. This article tries to fill this gap by providing rules and some sample phrases.

I recommend using StyleCop because its rules enforce some of the XML documentation recommendations from this article. Also check out the Visual Studio extension GhostDoc which automates and simplifies the writing of XML documentation.

General

• All XML documentation phrases should end with a period (.) and no blank:

  <summary>Represents an XML document.</summary>
  public class XDocument
  {
  

• The summary tags should only contain the most important information. For further details use an additional remarks tag. To avoid having too much documentation in your source code files, read this article which explains how to “outsource” documentation to an external file.

Classes

• Each class should have a summary tag describing its responsibility. The summary often starts with “Represents …“ or “Provides …“ but other forms also exist:

  <summary>Represents a collection of keys and values.</summary>
  public class Dictionary<TKey,TValue> ...
  {
      
  <summary>Represents a mutable string of characters. </summary>
  public class StringBuilder
  {
      
  <summary>Provides a generic view of a sequence of bytes.</summary>
  public class Stream
  {
  

Constructors

• The documentation of a constructor should be in the form “Initializes a new instance of the <see cref=”TYPENAME”/> class.”</see>:

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

Properties

• The summary of a property should start with “Gets or sets …“ if it is fully accessible, with “Gets …“ when the property is read-only, and with “Sets …“ if it is write-only:

  <summary>Gets or sets the name.</summary>
  public string Name { get; set; }
      
  <summary>Gets the age in years.</summary>
  public double Age { get { ... } }       
  

• Note: According to the very recommended book Framework Design Guidelines, write-only properties should not be used at all.

• A property of type bool should start with “Gets or sets a value indicating whether …“:

  <summary>Gets or sets a value indicating whether the entity is valid.</summary>
  public bool IsValid { get; set; }
      
  <summary>Gets a value indicating whether the service is active.</summary>
  public bool IsActive { get { ... } }
  

Events

• Each event should have a summary tag which starts with the words “Occurs when …“:

  <summary>Occurs when a person has been created.</summary>
  public event EventHandler PersonCreated;
      
  <summary>Occurs when a new person is about to be created.</summary>
  public event EventHandler PersonCreating;
  

• Note: Events should be named with a verb or verb phrase. Use the present and past tenses to express if the delegate is invoked before (e.g. Closing) or after (e.g. Closed) a particular event.

Methods

• Like the method name itself, the text in the summary tag should start with a verb:

  <summary>Removes the object from the list.</summary>
  ... 
  public void RemoveObject(object object)
  {
  

Method parameters

• Each method parameter should have a corresponding param tag containing a description of the parameter:

  ...
  /// <param name="personId">The person ID.</param>
  public Person FindPerson(int personId)
  {
  

• If the parameter is an enum or of type bool consider starting the description with “Specifies …“ (enum) or “Specifies whether …“ (bool)

  ...
  /// <param name="throwException">Specifies whether an exception should be thrown when...</param>
  public Person FindPerson(int personId, bool throwException)
  {
  

• Note: According to Clean Code you should not use bool method parameters.

Method return value

• If the method returns a value, you should add a returns tag which contains a description of the returned object:

  ...
  /// <returns>The person with the given ID.</returns>
  public Person FindPerson(int personId)
  {
  

• If the returned value is of type bool the documentation should be in the form “true if CONDITION; otherwise, false.”:

  ...
  /// <returns><c>true</c> if the person could be found; otherwise, <c>false</c>.</returns>
  public bool HasPerson(int personId)
  

Exceptions

• The exception exception tag contains the reason why the exception occurred:

  ... 
  /// <exception cref="FileNotFoundException">The project file could not be found.</exception>
  public static Project CreateProject(string projectPath)
  {
      
  ... 
  /// <exception cref="ArgumentNullException"><paramref name="action"/> is <see langword="null" />.</exception>
  public void Run(Action action)
  {           
  

• Tip: Have a look at Exceptional for ReSharper which greatly helps creating XML documentation for exceptions.

Final words

The rules in this articles are used in StyleCop and in the .NET Framework, therefore I think using them is best practice. Because it looks more clean to me, I write the opening tag, content and closing tag on a single line. Of course you can write them on multiple lines as proposed by the Visual Studio templates. For the generated XML documentation file it does not matter what style you are using.

What do you think about the described XML documentation rules? Are some rules missing in this list?