[Development] Ameliorate API Reviewing (Was: On the effectiveness of time based releases)

[Tony Van Eerd]

> Hi,
> >
> >  >- Have an "API review board", and for
> >
> > A review board would indeed be a good thing to have, not necessarily
> > restricted to API reviews only.
> >
> > The problem also currently is that reviewers are distracted by a lot
> > of mundane things (check for compilation, compiler warnings, check
> > indentation style, style issues, check for potential performance
> > issues, messages, spelling, functionality smoke testing, checking
> > autotests...), potentially over quite a few review rounds.
> 
> Actually, my thought about the API review board is that those reviewers,
> when pulled in, are looking only at the API. They can ignore all that other
> stuff, leaving it for someone else to review, and just leave their +1 if the API
> is good. Or a +2 if another developer already checked the implementation
> part.
> 
> > If there was a review board (supported by more automated testing)
> > making sure each change passes all those criteria before a developer
> > gets to see it, it would be a lot easier to focus on the API.
> >
> 
> One thing's for sure, if we have a review board we need a clear policy on
> whether to call them in first or second.
> 


How to Design a Good API and Why it Matters, Joshua Bloch
http://www.youtube.com/watch?v=aAb7hSCtvGw
(pretty much sums up the whole conversation, including the OP's points on why API is important.)

API and test/example code goes first.  Then implementation.

If you do the implementation first, you end up re-implementing stuff when a reviewer points out a better API.

If you do the API first, there _is_ risk that you might write an un-implementable API, but a good API reviewer should be able to see that an API will have implementation problems without seeing an implementation.  (Or at least ask the right questions, which then brings the implementation problems into view.)

Tony