Re: [boost] [Boost-users] [afio] Formal review of Boost.AFIO

Subject: Re: [boost] [Boost-users] [afio] Formal review of Boost.AFIO
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2015-08-29 13:06:21

On 29 Aug 2015 at 9:21, Michael Caisse wrote:

> >> There have been several suggestions (implicit and explicit) to move this
> >> type into the boost::afio namespace, but I haven' seen a response from
> >> you. Have I just missed it?
> >
> > It's more that the suggestion is irrelevant with respect to the
> > library. The code base as presented for review already exclusively
> > uses boost::afio::monad<T>. It is only the just-added workshop
> > tutorial which uses monad directly which made people think monad is
> > not an internal library, and which I now realise was a mistake due to
> > bad optics.
> >
> I think you may have missed parts of reviews. A few influential 
> reviewers [1]  have indicated that having components such as Monad and 
> APBind is a non-starter for a review or an immediate "no" vote (Vicente 
> [2] and Robert are just two on the user list... others on the dev list).
> 
> You have put a great deal of effort into this library and I would like 
> to see the chances of acceptance during the review not hindered by 
> non-essential choices. The bottom line is that implementations in the 
> boost::afio namespace will have different scrutiny than automatic 
> promotion to the boost namespace. Start with these concepts in the 
> boost::afio namespace and then at a later date, request a review to 
> promote them to the boost namespace as full-fledged libraries.

I appreciate all of what you just said. But please listen to what I 
just said: AFIO's use of these two dependent libraries is entirely 
internal in the implementation and header code. Where I came unstuck 
is that the documentation treats those two libraries as if there are 
not internal implementation libraries, and the documentation both 
refers to them by name e.g. Boost.Monad, Boost.APIBind and the code 
examples use them directly instead of via their boost::afio::* 
mapping. This makes them appear far more important than they are to 
the end users of the presented library.

> I don't think it is worth risking the review outcome on trying to get 
> multiple libraries into the boost namespace.

I think that most reviewers, once they actually looked at the code, 
realised that the use of Boost.Monad and Boost.APIBind is a purely 
presentational issue caused by a bad choice in the documentation. As 
I have said on many occasions now, I realise that was a mistake, but 
as I cannot change what has been presented for review I am stuck with 
it.

For the record, I estimate that all mention of APIBind and Monad can 
be completely eliminated from the AFIO documentation and externally 
facing API in about two days of work. They are totally incidental to 
AFIO the library presented here for review. This is why I said I 
would be upset with reviewers who refuse point blank to review this 
library purely on a documentation mistake if they then later on find 
severe design flaws in the library after I have invested an 
additional 500 hours in the lightweight futures refactor based on the 
presented API and design (which is my current estimate, and I am 
usually within 10% of my estimates when estimating on my own code). I 
think anyone would react similarly.

However after the many threads of discussion this week regarding the 
design tradeoffs in the AFIO API and design, I am confident that in 
any future review (if needed) that nothing not discovered in this 
review will come up. In this regard this review has been highly 
successful, and very valuable, irrespective of eventual outcome.

Niall

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