Suggestions for interface presented by library

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?

Thanks…it seems that Arcbotics have grown cold on releasing an update on the Sparki library…We have not seen the promised release last February. Are they working on it or have given up? They’re also silent on the issues discussed in the forum…

I think your naming convention is very good, wolfw. In my career as a software engineer I always tried to convince my coworkers how important choosing the right name was for software use and maintainability but it was often hard to get some to see it.

It is beginning to look like your library changes are going to have to become the official ones :slight_smile:

Thanks for your efforts,

Jerry

Quite contrary, we’ve recently posted quite a few updates:
github.com/ArcBotics/Sparki/tre … %20Library

We implemented a lot of the ideas wolf came up with, so thanks a lot for those!

We’ve been traveling a ton recently and handling the business side, but these should be posted in an installer package around Tuesday.

Thanks for the news. Looking forward to the formal release…

When do you expect to make that formal release?
When can we see release notes that summarize the fixes and enhancements that will be in that release?
What changes, if any, are planned beyond that release for the near-term future (i.e. next month or two)?

Just posted the new release and change notes:

I’ll have another post with more roadmap soon.

Thanks. I’ll check it out over the next week or two. (I already already have lots of other commitments for the next few days.)