As the title says: is it good practice to document thrown exceptions for interfaces? Does a generally agreed-upon best practice even exist? I feel it's an implementation detail that should not be included in the interface in any way, but at the same time I feel it's valuable information the user of the interface should have.
Whether comments like this are a good practice is a topic for another discussion, so to limit the scope of this question, let's assume that we've agreed that documenting code with comments like this is a good practice. Here with 'comments like this' I mean comments you can generate stuff from, i.e. documentation or metadata, and not just 'normal' comments. Examples include XML documentation, Javadoc, and Doxygen.
Now, which of these C# examples is the better practice, if any best practice can even be agreed upon?
Interface without exception documentation:
public interface IMyInterface {
/// <summary>
/// Does something.
/// </summary>
void DoSomething();
}
Interface with exception documentation:
public interface IMyInterface {
/// <summary>
/// Does something.
/// </summary>
/// <exception cref="System.Exception">Something went wrong.</exception>
void DoSomething();
}
Interfaces are contracts, if part of that contract includes a situation that a exception is thrown you should definitely include it in your documentation. You can see examples of exceptions documented in interfaces all over the .NET framework, for example IEnumerator has quite a few. (Text retreived by right clicking on a declaration of IEnumerator and navigating to "metadata view")
public interface IEnumerator
{
/// <summary>
/// Advances the enumerator to the next element of the collection.
/// </summary>
///
/// <returns>
/// true if the enumerator was successfully advanced to the next element; false if the enumerator has passed the end of the collection.
/// </returns>
/// <exception cref="T:System.InvalidOperationException">The collection was modified after the enumerator was created. </exception><filterpriority>2</filterpriority>
bool MoveNext();
/// <summary>
/// Sets the enumerator to its initial position, which is before the first element in the collection.
/// </summary>
/// <exception cref="T:System.InvalidOperationException">The collection was modified after the enumerator was created. </exception><filterpriority>2</filterpriority>
void Reset();
/// <summary>
/// Gets the current element in the collection.
/// </summary>
///
/// <returns>
/// The current element in the collection.
/// </returns>
/// <filterpriority>2</filterpriority>
object Current { get; }
}
An interface only defines the contract of the operations to be done not how they are implemented. Consider the following example:
void Sort(SortOrder order);
You could be tempted to add a throws ArgumentNullException if order is null comment but what happens if the implementor of the interface decides that receiving a null on the SortOrder means that it should use a default SortOrder? (wrong decision but a possible one). This should be a valid decision for the one implementing the interface, and if it is not an option to decide things like this then you should be offering an abstract base class that throws the exception instead of an interface.
Adding exceptions to the interfaces is like making interfaces inherit from the IDisposable interface. These things are implementation details that shouldn't slip into the interface definition.