Documenting Exceptions [DI22] [WHAT]
Tip DI22
Exceptions are unavoidable in many programming languages. Since an exception can result in serious issues like completely crashing a program, it’s important that they are handled properly. If a function can throw exceptions, make sure they are documented so that programmers using your function can handle exceptional cases properly.
There are at least two important things to document with exceptions:
The type of the exception.
Some indication of conditions under which the exception may be thrown.
How specific you get with this documentation depends on your specific scenario and how a function is intended to be used. Think about users of the function and what they would need to know to properly use it. What kind of interface is your function providing?
See the following examples:
Having more different kinds of exceptions a user needs to know about can increase the documentation creation and maintenance burden for them. Think carefully about the use of exceptions in your error-handling approach. If exceptions are inevitable for a given function, see if there are ways you can simplify things both for your users and yourself.