Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial

Subject: Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-01-26 06:15:31

On 25/01/2017 16:22, Andrzej Krzemienski wrote:

> Ok, so I had a short glimpse at Part A. Actually, the first thing I did was
> to scroll down to the example showing how I will be using this library.
> Again, I feel uncomfortable about the choice of the example (so I changed
> the irritation into non-comfort). The situations that are tested, I would
> classify them as precondition violations, and I wouldn't think of checking
> them in return value. If this was a real program, and I didn't trust the
> values of x and y, I can check the preconditions prior to invoking
> functions:

I couldn't agree more. It's an example of bad design and programming.
But I had at least five people email me saying "please put the Rust
example of use of Result side by side with an example of C++ Expected".

> I mean, if it is equally easy to check the condition before and after the
> function, it is better to do it before, and I do not have to "pollute" the
> return value with potential error conditions. I think the value of these
> expected<> types becomes clear, when we cannot see the erroneous situation
> from the arguments. Maybe a better illustration of expected<> with a code
> would the following situation:
> 
> Upon closing the application, I store its state in a text file. When I
> reopen the application the next time, I load the state from the file. Here
> is the function:
> 
> expected<state, error_conditions> state = load_state();
> 
> And now, the error conditions are:
> * file missing
> * file is not a text file
> * file contains erroneous contents
> 
> And I might want to respond to each of these conditions in a different way.

The first version of the tutorial had a reduced real world use example
from AFIO's implementation of opening a file where we perform a series
of syscalls and do different stuff depending on the result<T>'s
returned. Everybody hated it, they said it was too confusing. Yet in
fact the use of result<T> has *greatly* simplified that code. In AFIO v2
it's merely dozens of lines, in AFIO v1 it was approaching a thousand
lines so the use of Outcome has been a big improvement in readability
and maintainability.

I suspect people want contrived toy examples rather than examples of
what you'd actually write. I remember thinking the same about the ASIO
tutorial, and I personally speaking found the ASIO tutorial so reduced
in real world detail as to be confusing at best, productivity damaging
at worst. You end up having to grok through the ASIO source code to
figure out answers to stuff. Not a good tutorial.

So I'm really not sure what to do. I've slowed down the pace of the
tutorial several fold over the original now to the point where it's
become anodyne. I've reduced the length of the code examples so they
always fit onto a screen because according to feedback anything longer
than a single screen is "too long". I've also ramped up the frequency of
code examples because my prose is "too confusing" and "you need lots
more C++ code examples". But all this hand holding comes with the cost
that the code examples become really contrived, and the tutorial has
become so long it needs three parts, which is frankly ridiculous for
something so simple as a slightly enhanced std::optional<T> with a bit
of std::variant<...> muxed in. I really don't get what's so hard here,
just throw std::optional and std::variant into a bowl and apply a
blender. All the APIs and semantics stay the same and there are no
surprises in behaviour, it's all STL idiomatic. You're done.

I'm still aiming to end Tutorial part C with a real world code example
that is actually realistic and taken from actual use case. It will,
necessarily, span multiple screens. But I suspect I won't be allowed
anything but daft examples in the middle. Sorry.

But thanks for your feedback. Much appreciated and keep it coming!

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/