Re: exception handling anti-patterns in documentation

From: Emil Dotchevski (emildotchevski_at_[hidden])
Date: 2022-05-29 01:17:38

On Sat, May 28, 2022 at 3:39 PM Andrzej Krzemienski via Boost <
boost_at_[hidden]> wrote:
>
> Hi Everyone,
> I wanted to share an observation. A number of Boost libraries, in
> documentation, when it comes to demonstrating that a given function throws
> an exception, has a code sample like the following:
>
> try {
> >   lib::function();
> > }
> > catch(lib::exception const&) {
> >   // handle failure
> > }
> >
>
> This applies for instance to:
> * Boost.Lexical_cast:
>
https://www.boost.org/doc/libs/1_79_0/doc/html/boost_lexical_cast/examples.html
> * Boost.Optional:
>
https://www.boost.org/doc/libs/1_79_0/libs/optional/doc/html/boost_optional/quick_start.html
> * Boost.URL, waiting in the review queue:
> https://master.url.cpp.al/url/parsing/url.html
>
> What bothers me is that this is a very dangerous antipattern related to
> handling exceptions.

I agree, it is not the job of the documentation of a function to show how
to handle errors, only to specify the behavior of the function. Ideally
this should be done formally, using this pattern:

1) Requires: lists the requirements that must be met in order for the
function call to be valid. The user is not allowed to call the function
otherwise.

2) Effects: specifies how the state of the program is altered by the
function call.

3) Postconditions: the conditions that are guaranteed to be in place upon
return from the function (if it doesn't throw).

4) Throws: lists exceptions that may be thrown if the postconditions could
not be established.

5) Exception safety: specifies the state if an exception was thrown.

For an example, see the documentation of the pointer constructor of
shared_ptr:
https://www.boost.org/doc/libs/1_79_0/libs/smart_ptr/doc/html/smart_ptr.html#shared_ptr_members
.

That said, it can be useful to demonstrate how to handle errors, but this
wouldn't be attached to a particular function -- rather, it would show a
pattern of correct error handling using the library.