Re: [boost] [outcome] Feedback on parts A and B of Tutorial mk III requested

Subject: Re: [boost] [outcome] Feedback on parts A and B of Tutorial mk III requested
From: Asbjørn (lordcrc_at_[hidden])
Date: 2017-01-30 13:20:50

On 30.01.2017 11:19, Niall Douglas wrote:
>
> I am truly hoping that this will be the last time I ask for feedback on
> Outcome's tutorial as this is the third complete rewrite. Many thanks
> for all the feedback so far, this Mk. III tutorial wouldn't look like
> this without all your help.
>

Just some semi-random comments from a "plain" Boost user, who also read the 
initial version of the docs.

The current form is much better than the initial version. It was easier to skip 
the parts that I do not care much about, and easier to follow what the goal of 
the library was. As someone who hasn't read anything about expected<T,E> before, 
it was nice to have a section on it.

I overall liked the code examples, they worked much better for me than the 
previous ones.

However I do think the name "Tutorial" is a bit of a misnomer, and the parts A, 
B and C should be renamed to "Background", "Rationale" and "Introduction" 
respectively (or something similar). Most of part C is introducing the API, and 
the full tutorial bits, when ready, really should stand out a bit more compared 
to the current A, B and C sections.

In part B I think you should drop the inlined list of std:errc members, instead 
linking to it somewhere. Then you could simply write:

"The third reason is that the C++ 11 standard library already provides an enum 
of the most common error codes for you. It's called std::errc and it has the 
standard POSIX error codes. Most of the time you'll find that whatever custom 
error code domain you may want to write can be adequately covered by std::errc. 
In fact, let's try it:"

The list, while a useful reference, adds to the "wall of text" feeling that part 
B already suffers a bit from.

Going back to the start, I think rephrasing the initial portion of the 
description section to focus on Outcome rather than expected<T, E> would be 
beneficial. As it reads now, I still come away from this thinking it's a helper 
library to expected<T, E>, rather than something that could very well be used on 
its own.

Just an example:

"This is the Outcome library. It' a Boost C++ 14 library intended for 
ultra-lightweight error handling in large C++ codebases, providing a more 
expressive and type safe alternative to integer error codes or enums.

Unlike alternative implementations, it works perfectly with exceptions and RTTI 
disabled and is thus suitable for low-latency/games/finance/SG14 users. One 
could view Outcome as a minimum overhead universal outcome transport mechanism 
for C++, hence being named "Outcome".

The Outcome library provides an implementation of expected<T, E> (which is on 
the C++ 20 standardisation track), with the expected<T, E> refinements 
outcome<T> and result<T>."

Now I'm just a n00b, but I get worried about the raw char*'s everywhere. I know 
you're aiming for maximum speed, but couldn't the interface have std:string 
overloads as a safer alternative? At least for things like 
error_code_extended::extended_message(). I don't generally care much for the 
brute-force performance of my error handling code, it's not the hot path.

Personally I like that you've removed the word "monad" for most of the 
documentation. It's one of those concepts I sorta know what is, but I still have 
to do a web search each time just to remind me. Though in part C one is 
introduced to monad_error and friends. Now, _I don't mind this_, however I think 
it would be nice to have a _footnote_ here to quickly explain where the name 
comes from, with a link to some page with more info on monads.

Anyway, I now got a much better impression of what this library is about than 
the initial version of the docs. It also presented Outcome as a useful and 
interesting library, and as something I would want to try.

Cheers
- Asbjørn