exception handling anti-patterns in documentation

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2022-05-28 22:39:20

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. If there is any benefit to be had from exceptions, it
is that they separate the "positive" control flow form the "negative"
(failure handling) one. Whereas in the examples like the one above it is
quite the opposite: we are trying to catch the exception as soon as it is
thrown. This is usually the cause of bugs and resource leaks. Such examples
also lead many young programmers into thinking that exceptions are
difficult or illogical. But they are not illogical: it is antipatterns like
the one above that, which are working against the design of the exception
handling mechanism, that confuse the programmers and enforce bad habits.

One could say that the goal of the documentation is to demonstrate, in an
efficient way, the interface of the library: not to teach how to program.
But I would disagree. I have always considered Boost libraries to be more
than that. I personally learned a lot about how to program, organize my
code and organize my thinking about abstractions from reading the
documentation of Boost libraries. Boost is a place to promote better
programming practices. And these "catch immediately after throw and
swallow" examples just do a disservice to the community.

I would like to know if there are more people in this list that feel the
same way. Maybe we could come up with a systematic way of demonstrating a
throwing library interface, or guidelines for documentation authors.

Regards,
&rzej;