I have a suggestion or request for future, official library releases.
Function calls like sparki.lineCenter() are confusing. What exactly does this function return? It’s actually returning a brightness level, so I suggest that this function be named more descriptively, such as sparki.brightnessOfLineCenter(). This longer name is more work to type, but I don’t have to look at the documentation to figure out whether a high number means that the sensor is seeing a bright or dark object. With “brightnessOfLineCenter”, the name implies that a higher number means more brightness. (In fact, there was an error around this very issue in the line following sample code. With better naming, this error might have been avoided.)
So I’d like to see all property or query functions be named, such that the names provide solid clues about how to interpret the returned values, as in my brightnessOfLineCenter example.
For action functions, I suggest the structure . Some functions in the standard library, such as sparki.moveRight(), already follow this structure, but then there’s sparki.gripperOpen() which puts the verb at the end for no good reason. And sparki.RGB() is yet another flavor; it should be something like sparki.setLedColor().
Sparki is supposed to be easy to use and accessible, and I think changes of this sort can move it to closer to that goal.
I’ve been making changes like this in my own version of the library (what I posted in New (unofficial) library for wheels and gripper and additional work I’ve done since), but I’d rather not have to maintain my own version of the library.
Thoughts?