Re: exception handling anti-patterns in documentation

From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2022-05-28 23:40:28

On Sat, May 28, 2022 at 3:39 PM Andrzej Krzemienski via Boost
<boost_at_[hidden]> wrote:
> * Boost.URL, waiting in the review queue:
> https://master.url.cpp.al/url/parsing/url.html

Boost.URL is designed for the model where a thrown exception
terminates the program. Such as when the author knows that the inputs
are valid. People writing Real World Applications (TM) are not going
to be throwing on untrusted inputs, they are going to be using the
APIs which use error codes.

> What bothers me is that ...Such examples...lead...young
> programmers into thinking that exceptions are difficult or illogical.

The goal of the examples that show exceptions in the documentation is
merely to demonstrate that the exception is thrown. It is expected
that the reader is in possession of sufficient ability so as to be
able to make a leap of induction and apply this knowledge to their
particular use case (where the exception handler may be in another
function).

> 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.

Yes that is precisely the mindset when I write documentation. I assume
that the user of the library already understands everything in the C++
language, everything in the standard library, and a reasonably average
grasp of algorithms and general terminology. And I have a very good
reason for doing so. It is because the user who lacks these things can
always go someplace else to learn it (or teach themselves). External
resources which specialize in teaching C++ are going to do a better
job than I could.

It is already hard enough to develop a Boost-quality library with
Boost-quality documentation. Trying to also teach novices the
techniques that are applicable to any code in general only creates
additional work. Or to put it another way, having N authors of N
libraries all trying to solve the same problem is not efficient.

> 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.

I think there is room for a project (or projects) aimed towards
providing code and exposition for the purpose of learning C++, aimed
towards individuals who do not "know Asio, know HTTP, know concurrent
programming, and know error handling" (these the requirements for
using Beast). This could be a Boost-branded offering available on its
own from our the new website, with its own pages and discussion area.
The C++ Alliance is open to explore implementing such a project if
there are volunteers. I imagine that if started, such a resource would
only continue to grow in size, utility, and participation over time
(as it likely could never be correctly described as "done").

Thanks