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-26 22:36:54

On 26 Aug 2015 at 5:31, Glen Fernandes wrote:

> > [Paul] Correct - and more - "that we wish and
> > trust Niall to get it right - eventually."
> 
> That did not sound like a strong "Accept" to me. It sounded
> more like "Not reject" and "Please resubmit for review [after
> getting it right, eventually]."

The negative review responses so far have fallen into these 
categories:

1. Not all the APIs it uses are documented (because they are in other 
libraries). I will not look at this library until that is fixed.

2. Not all the APIs it uses are documented (because they are in other 
libraries). It therefore should be rejected.

3. The documentation has severe issues and needs a very great deal of 
additional work before it could be considered Boost-ready.

4. I think the fundamental design is flawed for these reasons X, Y 
and Z.

Categories 1 and 2 are utterly useless to me. I appreciate the 
motives and where they are coming from, but let me be clear in 
return: if I bring AFIO back in twelve months time after lots more 
work, and those same people then say the design is fundamentally 
flawed for reasons X, Y and Z and should be rejected, I am going to 
be very upset with them indeed. I think anyone would understand where 
I would be coming from in that response.

Category 3 has been an eye opener to put it mildly. I don't 
personally think severely flawed documentation is a reason to 
outright reject though. I do think that insufficient documentation is 
a reason to reject, but nobody can claim AFIO isn't well documented, 
it's just badly documented in a highly inaccessible structure with 
all the wrong information in the wrong places. That said, I think I 
have the fundamentals right e.g. race guarantees documented per API. 
There is a good base in there, I just hadn't realised where people 
get mentally stuck until now.

Category 4 has been the most valuable, and that is exactly Thomas 
Heller's review. I personally believe AFIO's API design is the least 
worst possible given all the competing factors and pressures, else 
I'd present something better. However equally I may have chosen 
something wrong or misestimated the effect of some factor or 
pressure. Having to explain myself is immensely valuable - indeed 
right now it's 3.30am and I'm here typing this because I can't sleep 
thinking about how to explain my API design choices. Terrible on work 
life balance, hopefully great on a better API design if one is 
possible.

Niall

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