I've been thinking about how to find generally usable principles for certain API aspects, like when to check a function's parameters for validity.
An idea came to mind:
We could define some (two, three) levels of how low an API goes and define (and document) consistent behaviour around those levels.
For example, a high-level timer or socket API that is being used by any simple application has probably more need for parameter checking than a low-level interface that no normal user will ever see. On the other hand, low-level functions for accessing the flash will probably abstracted with a sane user API.
The idea is to document that some API's do need a deep understanding of what's going on, thus will be used by developers that don't need a high level of safeguards. We could omit a lot of extra sanity checks.
Other API's will be used by high-level programmers which might not know how to debug parameter mistakes, so checking function arguments is more important.
What do you think?