Using <exception> Tag in C# XML Documentation Comments

Aug 13, 2018 • 3 Minute Read

Introduction

Code documentation describes the intent of a software's code. This includes the intent or description of a class and its members, the parameters and the expected result, or the return value. An XML code comment must immediately precede a user-defined type (such as class, interface, or delegate) or its member (such as field, property, method, or event). XML code comments can be utilized by the IntelliSense feature of Visual Studio and VS Code to show information about a type or member; this information comes from what you put in your code documentation.

The XML documentation comment starts with /// and can contain recommended tags that give special meaning to the comment. One of those recommended tags is <exception> which we will be looking at in this guide.

The Tag in Action

The <exception> provides a way to document what exceptions can be thrown for methods, properties, events, and indexers. It can be written as follows:

      <exception cref="member">description</exception>

The cref attribute contains a reference to an exception. Between the tag, you'll replace description with a description of the circumstances in which the exception is thrown. Let's look at following code definition:

      class Program
{
  private static int _age;

 static void Main(string[] args)
 {
   Console.WriteLine("Hello World!");
   Age = 14;
 }

 /// Client's Age
 /// <exception cref="System.ArgumentException">Thrown when age is set to be less than 18 years.</exception>
 /// <exception cref="System.ArgumentOutOfRangeException">Thrown when age is set to be more than 70 years.</exception>
 static int Age
 {
   get
   {
   return _age;
   }
   set
   {
   if (_age < 18)
   {
     throw new System.ArgumentException("You must be older than 17");
   }
   if (_age > 70)
   {
     throw new System.ArgumentOutOfRangeException("You can't be older than 70");
   }

   _age = value;
   }
 }
}
    

Above, we have an Age property which throws an exception when it is set to be less than 18 or greater than 70. The cref attribute holds a reference to the thrown exception, while the description of when the error is thrown is placed between the tags. This information is valuable when other people use your code so that they can tell what to set this property to in order not to get an exception. The IntelliSense can show this information as you access this property or when you hover over it.

Wrap Up

XML Documentation comments can be extremely useful in helping you, or other programmers who will use your code, to understand the code better. We looked at the <exception> recommended tag which provides a way to document the exceptions a method, property, event, or indexer can throw. You learned how we can see this information through the IntelliSense.

Use XML documentation comments as much as possible and give more meaning to your code. See the C# documentation for more recommended tags.