[Development] API review and API quality

[Andreas Hartmetz]

Hello,

Due to a recent problem I had with an API addition (solved while writing 
the E-Mail about it, the rubber duck technique worked!) I noticed, not 
for the first time, something missing...

the Trolltech API review process.
The thing that ensured that (almost) all new API made sense to humans 
semi-informed about the subject matter the API deals with.
I don't know how it was done - I recall some rumors about people getting 
into a room and reviewing API on a projector or something.

Nowadays, API not contributed by TQtC is not-really-reviewed on Gerrit. 
Gerrit is somehow much more detail-oriented, and criticizing "too 
subjective" stuff is frowned upon. There's a fine line between annoying 
people for no good enough reason and being too lenient and letting bad 
code / API slip through.
For API, due to its somewhat subjective nature, I would argue that the 
level of strictness required to achieve a good result is already more 
strict than what is perceived as annoying people for no good reason. It 
doesn't help that the strictest and most nitpicky reviewers generally 
care the least about API.

So yeah, I came with a problem and no good suggestion for a solution.
I would be fine with TQtC doing API reviews at some point well before 
release and telling everyone the results in time to improve their code 
additions for that release, but that's just my opinion.
I suspect that a room full of "dude, that API sucks, you can't ship 
that" makes more of an impression on perpetrators of subpar API than one 
or two -1 for "only" soft reasons on Gerrit. At an API review meeting, 
there *will* be a sufficiently large number people to achieve that 
effect. On Gerrit, well, most people prefer doing something else, like 
micro-optimizing something. Nobody can argue with contributions like 
that. But they are perhaps not as important as ensuring API quality.

Everything I have written about API applies to documentation as well. It 
seems like whatever the implementor writes is accepted and that is that. 
AFAIU that was not exactly how it used to be done at Trolltech when it 
was still called Trolltech?

tl;dr: API quality is not something people work on casually and 
voluntarily, it seems like it needs more / more suitable process to 
achieve.
(Also, nobody likes process.)
Now what?

Cheers,
Andreas