Quantcast

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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Niall Douglas
Dear Boost,

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.

Part A is 100% on pure expected<T, E> as currently before the standards
committee. It has nothing to do with Outcome, but places Outcome in context.

Part B is a polemic on why people should not use arbitrary type E in
expected<T, E> and instead should restrain themselves to either E =
std::error_code or E = std::exception_ptr.

I'm requesting feedback on parts A and B of the tutorial which I think
are mostly complete now. Specific feedback on these topics is
particularly welcomed:

1. I've tried to make some of the code examples in Part A less
contrived. Are there any obviously specific additional things I can do
(note Parts B and C have more realistic programs)?

2. Are you convinced by the end of Part B that using arbitrary types for
type E is a bad idea? If not, what did I fail to do in my explanation?

Many thanks in advance.

Niall


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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Niall Douglas
Bah, forgot the links:

Part A:
file:///C:/Users/ned/Documents/boostish/outcome/doc/html/md_doc_md_02-tutorial_a.html

Part B:
file:///C:/Users/ned/Documents/boostish/outcome/doc/html/md_doc_md_03-tutorial_b.html

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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Niall Douglas
On 30/01/2017 10:24, Niall Douglas wrote:
> Bah, forgot the links:
>
> Part A:
> file:///C:/Users/ned/Documents/boostish/outcome/doc/html/md_doc_md_02-tutorial_a.html
>
> Part B:
> file:///C:/Users/ned/Documents/boostish/outcome/doc/html/md_doc_md_03-tutorial_b.html
>

By which I really meant:

Part A: https://ned14.github.io/boost.outcome/md_doc_md_02-tutorial_a.html

Part B: https://ned14.github.io/boost.outcome/md_doc_md_03-tutorial_b.html

So sorry, I'm late out the door to work.

Niall

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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Asbjørn
In reply to this post by Niall Douglas
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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

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

Great. They're surprisingly hard to get right without annoying people.

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

Feedback has been pretty universal that people want an expected<T, E>
implementation and they don't really want anything other than that.
Hence Outcome is now primarily an expected<T, E> implementation, which
is a bit sad for me personally, but hats off to Vicente and all that
effort he's put into WG21 on getting Expected to where it is.

Hence Part A really does need to be a tutorial of some form. Part B,
thanks to Reddit feedback, is going to mutate from a polemic against
certain naive use practices of expected<T, E> into a more "this is the
way we really strongly suggest you ought to use expected<T, E> instead
of what you thought you would do". That then segways into Outcome's
refinements which are basically hard codes of the best practice.

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

It's okay by me if Outcome becomes perceived as an Expected
implementation with a few extensions and helper utils. It's definitely
what people want, and I'm a believer in giving people what they want
even if I don't personally think it's good for them.

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

Agreed. I intentionally left them out for the peer review because if I
include them then they form part of the review, but you can expect
string_view and gsl::span<> overloads to turn up if Outcome is accepted
into Boost.

Also, some really do care about maximum error handling performance,
specifically me because AFIO v2 needs failure to be handled as quickly
as and equally to success :)

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

Again if I did that then monads would form part of any review. So if a
review ever comes, my response will be "the names are just a collection
of ASCII bytes". I've already disabled by default half the stuff Outcome
can do for the review, and purged any mention of those facilities from
the docs apart from suggestive nomenclature.

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

Thanks very much for your detailed feedback, and I'll incorporate the
stuff you suggested that I didn't respond to. I agree that Part A, B and
C of the tutorial isn't ideal naming. I'll see what I can come up with
instead.

Niall

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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Asbjørn
On 02.02.2017 00:19, Niall Douglas wrote:
>>
>> I overall liked the code examples, they worked much better for me than
>> the previous ones.
>
> Great. They're surprisingly hard to get right without annoying people.

I appreciate that this can be a very difficult task. It's a fine line between
obscuring the library functionality with clutter and hiding important details.


>> 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).
>
> Hence Part A really does need to be a tutorial of some form.

I just react to the word tutorial. For me, any tutorial in the Outcome
documentation should be strictly regarding Outcome, not something else.

I have no objections with part A having the _form_ of a tutorial though.


> Agreed. I intentionally left them out for the peer review because if I
> include them then they form part of the review, but you can expect
> string_view and gsl::span<> overloads to turn up if Outcome is accepted
> into Boost.

Excellent.


> Again if I did that then monads would form part of any review. So if a
> review ever comes, my response will be "the names are just a collection
> of ASCII bytes".

Fair enough. I know it's been a touchy subject.

Cheers
- Asbjørn

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Loading...