[Microbit-Python] Accessor API design on the micro:bit

[Larry Hastings]

On 11/01/2015 03:59 PM, Damien George wrote:
> Actually, getting the value of the accelerometer is doing something
> very non-trivial: it does an I2C read on the bus to update the value.
> Whether this implementation detail (is it an implementation detail?)
> should factor in to the decision to use (or not) properties is an
> interesting discussion.

Well, again, technically, right now the act of reading the device is 
done asynchronously in the idle thread.  Directly interacting with the 
"accelerometer" object doesn't cause a read.

Plus, you read all three values at once, and you only do so when the 
device has new values to read.  So even if we changed it so querying the 
accelerometer for its X value caused an I2C read, it wouldn't happen 
every time.

This is one reason why you have to go with a /subjective/ assessment, 
whether or not doing something "feels" like it has code behind it.  
Implementations change back and forth.  So as API designers we should 
decide whether or not getting the x value from the accelerometer "feels" 
like it's doing work.


> One big advantage of making everything functions is that you have room
> to grow the API in the future if the function call needs to have
> arguments added to it.  For example, maybe getting the accelerometer
> value has an optional argument to force the update of the value (ie do
> an I2C read even if one was just done), or maybe there's an argument
> to specify the g-range.

As they say on python-dev: YAGNI.  (For those unfamiliar: an acronym for 
"You Ain't Gonna Need It".)  I wouldn't want to mix in the g-range in as 
a parameter, and I think "force a fresh read" would be fine as a 
separate function call, were we to add such functionality, which I don't 
think anyone is currently proposing we do.

The best API for the accelerometer IMO would be for it to automatically 
publish fresh values to the user, and I believe that's not merely 
achievable but actually reasonably straightforward. Implemented like 
that, I foresee no eventuality where we'd have to add parameters to 
"read the current x value from the accelerometer".  So a member / 
property should permanently suffice.


> Also, consider the button API: do we want button.value as a read-only
> property?  What about button.was_pressed()?

Speaking personally--I'm not sure.  Maybe I should take a step back and 
look at the API overall, and make a specific proposal about? I've been 
thinking about doing this anyway.


> My argument is: functions are more general/powerful than properties
> and are going to be needed in some places, so best to just have
> everything a function and teach only that concept.

I don't know what the curriculum will look like, but I would be very 
surprised indeed if it permanently skipped variables and only ever 
taught the students functions.  Since presumably the students /will/ be 
taught about variables, I don't see a need to remove any and all 
variables (or things that merely look like variables!) from our API.


Cheers,


//arry/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/microbit/attachments/20151102/92c41e5c/attachment.html>