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

[Larry Hastings]

On 10/30/2015 03:25 PM, Michael wrote:
> The argument that convinced me was Tom Viner's one summarising the 
> discussion from the sprints - the fact that it gives you additional 
> help as to what will happen when you do something, and that something 
> is available.

I don't appear to have Tom's summary.  And I don't know what help you're 
talking about--do you mean docstrings?  Right now I didn't think hardly 
anything in the micro:bit API had docstrings, and I didn't think that 
was likely to change.  And while you and I are comfortable in the REPL, 
I'm not convinced that the kids will spend a lot of time there.


> That's perhaps why properties would need explaining - the value 
> accelerometer.x would return would change without you doing anything, 
> but other named values don't.

Is that actually a problem?  Surely children are familiar with objects 
that change their own state--clocks and televisions for example.  
Someone who's new to programming wouldn't have the preconceived notion 
that "accelerometer.x won't change until I tell it to".  I'm not sure it 
needs explaining past "accelerometer.x is the current value of the 
accelerometer, it refreshes itself".

Incidentally, the way it works right now, there's an idle thread that 
among other things updates the accelerometer and compass readings.  
accelerometer.get_x() currently doesn't compute anything, it's literally 
one line of code, returning a private member of the object.  So it 
/already/ changes without you doing anything. The fact that it's hidden 
behind a function call is a bit misleading, if anything.


> So, while I'm in favour of picking one approach - descriptors all the 
> way or get/set all the way - I can see good reason for actively 
> choosing to break that rule. If we do, we can then signpost that it 
> works differently and why.
>
> The niggle at the back of my mind is that if you do "accel.x/y/z" this 
> way, why not temp, "compass", time, pins, buttons and LEDs - as raised 
> back in the thread "Flat API".

The rule I use, which I admit is a bit subjective, is that descriptors 
are good if:

  * you don't need to specify parameters (because, after all, you can't
    specify any)
  * you feel like you're passively getting a value, not executing live
    code (e.g. Subprocess.return_value shouldn't execute the program,
    just return the result once it's been executed)

A little magic behind a descriptor is okay, like constructing a database 
query object then accessing fields might actually lazy-run the query 
from inside a descriptor.  Unsurprisingly, I think computing the current 
value of an accelerometer axis is a fine candidate for a descriptor ;-)


If descriptors were bad, Guido would hop in his time machine and take 
them away from us,


//arry/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/microbit/attachments/20151031/9f427438/attachment.html>