Documenting exceptions

Question

I have the following public interface

public interface Bar{
   public void DoStuff();
}

with an internal back end class

internal class BarImpl : Bar{
   public void DoStuff(){
     // throw exception if invalid state
     // do something
   }
}

The question:

• Only BarImpl implements the Bar interface.
• BarImpl can throw exceptions in the DoStuff method.

Does it make sense to document these exceptions in the Bar.DoStuff xml doc?

Thanks in advance,

Answer 1

Yes - this would be the case even if BarImpl isn't the only implementor.

The example I like to use is the Stream class where the abstract Read method lists a whole load of exceptions that users of a Stream instance might expect to be thrown when using this method, and in turn the implementors of this class should throw under various scenarios.

Answer 2

Yes it does. It helps other developers to be prepared and to handle any exception that might occur. Think how many times it helped you prepare yourself for exceptions by going through MSDN documentation.

Answer 3

I only document exceptions which could be handled. Doesn't make sense to document any other exceptions. My definition of "handling" exceptions is that the method can deliver the promised result by catching the exception.

So this answer is only for those exceptions:

If you want to follow open/closed principle you should document the exceptions for the interface and not the concrete class. And all implementations must throw the same exception when the same scenario occurs.