TICS Coding Standard Viewer 
TIOBE Software Quality Framework
Print-friendly version
©TIOBE Software www.tiobe.com
 
C# Coding Standard
Search

Rule:  8@104

Synopsis:Document the exceptions that are explicitly thrown by a method or a property
Language:C#
Severity Level:8
Category:Exceptions


Description:

Describe the recoverable exceptions using the <exception> tag.

Explicit exceptions are the ones that a method or property explicitly throws from its implementation and which users are allowed to catch. Exceptions thrown by .NET framework classes and methods used by this implementation do not have to be listed here.

Example:

/// <exception cref="FileNotFoundException">Thrown when somepath isn't a real file.</exception>
public void MyMethod2()
{
    FileInfo fi = new FileInfo(somepath);
    if (!fi.Exists)
    {
        throw new FileNotFoundException("somepath doesn't exist");
    }
    ...
}

This rule is only mandatory for public and internal methods and properties, because the exceptions are in fact part of the API and as such they need to be documented in the same way that everything else about public and internal APIs needs to be documented.

Note also that private methods preferably should not throw exceptions in the first place, since exceptions should be used to handle exceptional situations, and not as a control flow mechanism. There are more graceful and cheaper ways for private methods to deal with this.