3 ms·
I've created more than a few and IMO there's a reasonable approximation of perfect, namely an API which is possible to explain completely in reasonable prose.
by Arnt 14y ago
I've created more than a few and IMO there's a reasonable approximation of perfect, namely an API which is possible to explain completely in reasonable prose.
If the documentation has to go off and spend much verbiage on side cases, something's wrong. There's an imbalance in the API that's reflected in the documentation.
If the first few sentences of the documentation read like committeework, or sound like the explanation of the explanation, then something's wrong. The API is not going to be compatible with its users.
If the documentation talks more about specific use-cases instead of classes of behaviour, then something's wrong.
IF the documentation tells you to do this, then that, then that, then something's wrong. It should talk about useful, describable atoms, not things that make sense only as a sequence.
There are a few more.
All this doesn't help to improve an API before release, at least not directly. But reading the documentation makes it easy to detect API brokenness while it can still be unfucked.