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

Subject: Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial
From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2017-01-16 07:13:56

2017-01-11 13:53 GMT+01:00 Niall Douglas <s_sourceforge_at_[hidden]>:

> Dear Boost,
>
> Last November you gave me some valuable feedback on rewriting the
> tutorial for Boost.Outcome, a C++ 14 library providing a
> factory and family of policy driven lightweight monadic
> value-or-error transports. I recently came out of employment contract
> and so have had the time to rewrite Outcome's Tutorial (anyone
> interested in employing a remote working C++ consultant please do get in
> contact). I'd appreciate feedback on https://ned14.github.io/boost.
> outcome/:
>
> 1. Is this rewritten tutorial too simple, too detailed or about right?
>
> 2. Do you feel you could use Outcome in your own code without difficulty
> after reading it? If not, what information is missing?
>
> 3. Are you persuaded of the merits of using Outcome after reading it? If
> not, what else do I need to say?
>
> The first FOUR sections at https://ned14.github.io/boost.outcome/ have
> been rewritten by me to hopefully reflect the feedback you gave me last
> November, so these have been refactored so far:
>
> * Description, Prerequisites and Support
> * Installing, building and testing Outcome
> * Quick start for the expert
> * Tutorial
>
> The package repo install methods haven't been implemented yet, these are
> marked in the docs as todo.
>
> These sections have yet to be refactored:
>
> * Frequently Asked Questions
> * Advanced usage: Outcome as a Monad
> * Outcome and the upcoming std::expected<T, E>
>
> Many thanks in advance for any feedback received.
>
> Hi Niall,
I intend to review the docs again. So far I had only a glimpse at the
initial page, and it really looks good. I was now able to grasp the idea of
the library in less than a minute.

One thing I wanted to bring up immediately, is not really related to your
library but to a detail in the example. It uses `noexcept` to illustrate
that the function does not throw itself:

```
bo::outcome<int> getConfigParam(std::string name) noexcept;
```

I strongly believe that this is the wrong thing to do (or at least
controversial) to annotate a function that can fail-but-not-throw as
noexcept. It is more in the spirit of noexcept intentions to indicate a
no-fail guarantee rather than the no-throw guarantee.

I have provided the justification for this claim in the following post:
https://akrzemi1.wordpress.com/2014/04/24/noexcept-what-for/

And conversely, only because you guarantee that a given function never
throws, it does not immediately imply that a function should be declared as
noexcept.

I think that your example would not suffer if the noexcept is removed. It
still does the good job of illustrating the intent. But you would avoid
certain controversies that might divert the reader's attention from the
main point.

Regards,
&rzej;