API proficiency levels

Development archive
#1

Hey guys,

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?

Kaspar

#2

Hi Kaspar,

in general I like the idea, one problem I see is however, that is not always clear, to which level an API belongs (e.g. the GPIO API is definitely used also by high-level application programmers, while still belonging to the low-level peripheral drivers...).

Cheers, Hauke

#3

Hey,

#4

Did the discussion about redundant parameter validations and DEVELHELP die?

I like the idea of getting rid of some redundant input validation. For example, if you are internally using spi_transfer_byte to provide spi_transfer_regs, then if the SPI device is valid for the first byte transferred, then it is probably going to be valid for the rest of the bytes in the same function call chain.

There was some discussion about null pointer checks in a PR or a mailing list thread but I did not find it when I did a brief search.

Best regards, Joakim Gebart www.eistec.se

#5

Hi,