Re: [review][LEAF] Review of LEAF starts today : May 22 - May 31

From: Christian Mazakas (christian.mazakas_at_[hidden])
Date: 2020-05-30 22:33:39

This is my review of LEAF as a long-time user and proponent of Boost:

> Please provide in your review information you think is valuable to
> understand your choice to ACCEPT or REJECT including LEAF as a
> Boost library. Please be explicit about your decision (ACCEPT or REJECT).

ACCEPT

>  - What is your evaluation of the design?

It's similar to many Boost libraries before it in that it's incredibly
rich, nuanced and can
give you the most cryptic and hard-to-decipher compiler errors.

However, the more I used it and become accustomed to its idioms, the more I
found myself
enjoying it.

`preload` is the most simple and elegant abstraction I've seen for
incrementally adding information
to an error context as it travels back up the callstack. I've seen similar
patterns be attempted in Go
and LEAF far and away has the most powerful and type-safe approach.
`preload` should, however,
have a [[nodiscard]] attribute attached to it.

`try_handle_all` is a nicer alternative to exception handling though it can
be difficult to tell if an overload
is going to be called when trying to match up against errors. I'm assuming
this is simply because of my
inexperience with the library and is something that will be alleviated with
time.

The library also works very well with normal exception based code.
leaf::catch_ and leaf::exception_to_result
are useful abstractions that help the user integrate LEAF piece-by-piece
into the codebase which is important
when looking at updating existing code.

Because users can manually control the error context (including storing it
and using RAII-like wrappers to activate it),
it's usable in Asio which is a hard requirement for me.

Overall, the design of the library is quite powerful and is relatively
simple for how much it does.

>  - What is your evaluation of the implementation?

As a user, the only thing that matters to me is: is it better than I
could've done myself?

And the answer to that question is a resounding "yes!" Otherwise, the
implementation details
are best left evaluated by a fellow library author which I am not aiming to
be in this instance.

>  - What is your evaluation of the documentation?

Parts seemed out of line with what was in the examples (I'm thinking of
exception_to_result) but overall,
the documentation has good styling and goes into quite a bit of depth. The
examples in the source repo
are quite good as well. As a user, I found myself able to reference things
and get a working example
relatively quickly that show-cased the power of LEAF.

>  - What is your evaluation of the potential usefulness of the library?

Incredibly useful. When writing user-facing applications, it's important
that one gathers up appropriate data
to craft a useful error message to display. It's also incredibly useful
because of the type-safe matching in
try_handle_all.

Error codes are not sufficient many times and LEAF minimizes the amount of
boilerplate one would have
to use to update existing code.

>  - Did you try to use the library? With which compiler(s)? Did you
>    have any problems?

I did. It installed perfectly with CMake and was able to be
find_package()'d easily.

I used gcc 10.0.1 in WSL.

>  - How much effort did you put into your evaluation? A glance? A quick
>   reading? In-depth study?

I dedicated around 2 to 3 hours playing around with it in addition to
spending about an hour last
week reading the docs.

Even though I'm not fully adept with using the library, I see its
potential. Many Boost libs require
time to learn and digest and they're fantastic (I'm thinking of Asio,
Beast, Spirit) so I'm not holding
any stumbles I encountered against it.

>  - Are you knowledgeable about the problem domain?

If the problem is error handling, I'm decently well-versed. I've written
many user-facing applications
and have wound up reimplementing what LEAF does a couple of times.

Some closing thoughts...

LEAF doesn't have to be perfect to be accepted. I think as of now, it's
documented  and completed enough
that it can be picked up and used but more importantly, I think its core
goal is worthwhile enough that it should be
iterated on and refined by many users trying it out and providing their
feedback.

I've seen this pattern be re-implemented in Go and in many codebases I've
worked on professionally. LEAF far
and away has the best implementation I've personally seen and for that
reason, I think it should be wholeheartedly
accepted into Boost.

- Christian