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
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
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
-- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk