C# guidelines for exception documentation [closed]

Question

The API I'm working on is becoming quite large and now I'm working on some multi-threaded stuff, so I want to make sure that I know all exceptions that can occur at any given point. I know C# does not have checked exceptions that you have to declare with each method, like Java, but I figured I would do it in the documentation for each method.

Consider the following very simple example:

/// <exception cref="System.DivideByZeroException">oh no, divide by zero.</exception>
int someMethod(int a, int b)
{
    return a / b; //this might throw DivideByZeroException
}

//clearly this method can never throw a DivideByZeroException
int someOtherMethod(int a)
{
    return someMethod(a, 2);
}

Do I add the DivideByZeroException tag to "someOtherMethod"?

Of course this is just a very simple example and the real code is more complex, but sometimes I know an exception that a sub-method throws can never occur. Not because I catch it, but because I will always pass valid arguments to it.

If I want documentation for exceptions then I have 3 options:

1) Act like that exception will never happen and don't add the tag to the documentation (because it never will, and I have unit tests to back it up).

2) Add an exception tag for an exception that I know will never happen.

3) Do a try-catch and ignore, to make sure it will never happen, so I can remove it from the list of exceptions with good conscious.

I like option 1 the most, but is there any sort of guidelines for this?

Answer 1

I've never seen any kind of guidelines regarding this, but developers mostly logical people and expect to see in documentation exceptions that can occur and never see those that cannot. Just be logical, it is often much better than following guidelines (which is also important, of course).