Documentation of exceptions

[Dansk]

Hi all,

I'd like to document exhaustively the exceptions that could be thrown by
a method.

For instance :
I have a method Foo1 that invokes a method Foo2.
Foo2 throws a ProblemInFoo2Exception, but foo1 does not catch it.
I want to be able to say/document that foo1 could throw
ProblemInFoo2Exception.

Are there any tools/techniques that could help me to do that?

Thanks,

Dansk.

 

[Nicholas Paldino [.NET/C# MVP]]

Dansk,

There might be some static analysis tools to do this (a google search
will turn them up if there are any), but you have to remember that
ultimately it will get to the point of diminishing returns, because there
are exceptions that can be thrown that have nothing to do with your code.
Things like OutOfMemoryException, ThreadAbortException, etc, etc, could be
thrown by the CLR while your method is running.

 

[Jeroen Mostert]

I'd like to document exhaustively the exceptions that could be thrown by
a method.

Nobody's stopping you. Using XML comments:

/// <exception cref="Foo.FooException">Thrown when the foo bit inverts
during a neutron polarization cycle.</exception>
public void Foo() {
}

Unlike in Java, .NET does not make exceptions part of the method signature,
so you're on your own when it comes to documenting and implementing error
handling strategies. This is both a blessing and a curse -- the curse part
comes when a function throws an unexpected exception because the implementer
*didn't* document exhaustively and/or didn't make sure to wrap exceptions.
Unfortunately, the .NET common library is itself not exempt from these mistakes.

For instance :
I have a method Foo1 that invokes a method Foo2.
Foo2 throws a ProblemInFoo2Exception, but foo1 does not catch it.

Note that Foo1 might not have any reason to catch it. Ideally an exception
should bubble up to the place where the error condition can be meaningfully
handled, and this is not necessarily the immediate caller. Forcing that
leads to ProblemInFoo1Exception, and so on, to the point where the old
"check error return values" approach starts to look better.