Documenting Interfaces and their implementation

Question

Hi,

I'm decorating my C# code with comments so I can produce HTML help files.

I often declare and document interfaces. But classes implementing those interfaces can throw specific exceptions depending on the implementation.

Sometimes, the client is only aware of the interfaces he's using. Should I document my interfaces by adding the possible exceptions that could be thrown by its implementors?

Should I create/document custom exceptions so that interfaces implementors throw these instead of those of the framework?

I hope this is clear!

Thanks

EDIT jan 4th 2010: I decided to write a blog post about this and custom exceptions in .NET at http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

I am not sure I fully understood your question (and I'm a Java, not C# developer), but it seems you are asking about what is essentially an issue of polymorphism: if somebody uses a method on an interface that is declared to throw X and Y, what happens if an implementation throws Z?

One thing to follow is the principle of conformance, that essentially says that a subtype should conform to the behavior of the supertype. That is, if you are documenting that your method in the interface can only throw exceptions of one type (e.g., null pointer exceptions), then your contract with callers is that this is the only thing they should watch for. If you throw something else, you could be surprising them.

Documenting things about a specific subtype in the supertype not a good idea since it creates needless coupling. I would be more concerned about the fact that an implementation may behave differently than the declaration since that might suggest the declaration is not fleshed out enough.

Try to think what are all the types of exceptions that your method could throw. Create supertypes for them, and then explicitly declare in your interface method (e.g., this method can throw some "calculation exception"). Then, in your implementation, throw a calculation exception with more details, or throw some subtype of the calculation exception that is specific to the implementation, you would still conform.

Answer 2

I agree with everything Uri says - you should where sensible create custom exceptions that can be extended if required then a method which uses a parameter typed to your interface can catch that exception and it will catch subtyped exceptions as well.

Don't create them needlessly though, if there's an existing .Net Framework exception that describes your error condition use that

In terms of documenting for implementers you can use the remarks section of the comments (assuming you're using XML comments) to describe things like how you'd expect implementors to do things. Obviously this is in no way enforceable but it can serve as useful guidelines when a developer comes to use your API