API Design Guidelines

Some small points about API design that I find greatly affect usability...

Normalise Ranges

The ranges of values that user code sees -- what it passes to or queries from our API -- should be chosen to make it easiest for the user to program the math they want to do, rather than expose what the current hardware actually does. Typically that means ranges of 0..1 or -1..1. Our API should translate between these values & the hardware. So we'll need a thin hardware abstraction layer.

For example, if an LED has 16 levels of brightness, the user should control them by setting the brightness to some value between 0 and 1, not 0 and 15.

An example of an API that doesn't do this is Codea. I'm always wondering why my graphics aren't appearing and realise I've not multiplied the alpha by 255 and so they are being drawn with an alpha of leas than 1 -- e.g. transparent! Very annoying.

Time in Seconds

Time should be measured in seconds, not millis, represented as a double (if poss) not int. Maybe a duration type with different factory functions might be the way to go:

duration.secs(2.5)

Or

duration.millis(2500)

Under the hood we can represent it as an integral number of micros or nanos or whatever.

Vectors

This may be more applicable to graphics programming, but there's a lot of benefit in representing seemingly different things as vectors. E.g. don't have a distinct color type, represent colors as vectors in a 3d or 4d color space. Then you can apply vector and matrix math to derive values from different sources that would otherwise require a lot more explicit coding.