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

[Nicholas H.Tollervey]

Hi Larry (and Michael),

Larry, thank you for playing devil's advocate here and please remember
that I too am playing this role. Please also remember that I'm open
minded and not precious about my opinions ~ I'm exploring this API
problem and, for me at least, I tend to try different things out and
sometimes flip flop while I weigh the pros and cons for the different
sorts of users of the API.

Put simply, here's what's on my mind:

* The obviousness argument for the full ability range of 11yo kids that
Michael uses in his compelling. Accessors are the coding equivalent of
calling a spade a spade - it's hard to get confused by what they're
doing despite their verbosity and klunkiness.

* Alternatively, I also find it compelling that part of our job as
"teachers" is to promote good idiomatic programming so I like Larry's
KISS accelerometer.x. It's Pythonic and descriptors are part of the
language. It makes me rather uncomfortable that we're making our API
look Java-esque rather than Pythonic.

Upon reflection, as a music teacher I was used to exactly this situation
in a musical context - the general rule of thumb is to do the correct /
idiomatic thing (whatever that may be) and teach around it.

For example, rhythmic notation is all about fractions / ratios and ('cos
we're in Europe) weird historical names like "quaver" and "minim". I
couldn't ignore that, but I got quite good at teaching such things to
classes of 11yo containing a wide range of abilities - to the extent
that they could sight-clap rhythms and write down rhythmic dictation
after a few of weeks.

Part of me thinks we should just trust the teachers / learners. There's
also the argument that a bad teacher will bodge up accessor methods too.

I guess I'm saying that no matter what we do, we need to provide plenty
of idiomatic examples of different features of the language for teachers
and learners to study.

I started this email thinking I was for accessors but while re-reading
it I find myself more drawn to descriptors. Perhaps that's just a
symptom of it being Friday evening and I've had a hellish week at "real
work".

I'm going to sleep on it before commenting further. Please feel free to
shoot me down - as always comments, constructive critique and idea are
most welcome!

I hope we all agree that no-matter which way we go, we ensure it's
consistently applied throughout the API.

:-)

Best wishes,

Nicholas.

On 30/10/15 16:11, Larry Hastings wrote:
> 
> 
> I want to revisit something that was decided during the sprints at PyCon
> UK.  On a Github PR today (
> https://github.com/bbcmicrobit/micropython/pull/58 ) there was a short
> discussion about how to spell "give me the x coordinate reading from the
> accelerometer object".  I suggested "accelerometer.x".  In response,
> Damien George said:
>> We discussed this at length at PyCon UK: we use functions for
>> everything. It's more consistent (and setters like obj.attr = 1 can't
>> be used in a lambda, while obj.set_attr(1) can).
> 
> Nick Tollervey said, nigh-simultaneously:
>> I seem to remember having a conversation about get_foo() v foo or
>> foo() at PyCon UK. IIRC we agreed to keep such things as method calls
>> since that's a consistent pattern in the way the API is written. I
>> also remember a discussion about using explicit verbs in the method
>> name so kids immediately understood what it was they were calling.
>> I.e. get_foo() is more obvious than simply just foo().
> 
> I'm all for consistency, but in this case I think the group has chosen
> to be consistent in the wrong way. Things like "accelerometer.x" are
> /exactly/ what the descriptor protocol is for. The spelling couldn't be
> clearer, not to mention it's easy to read and pleasingly short to type.
> I would absolutely 100% design my API that way for adults and I think
> it's better for kids too.
> 
> It's true that you can't use an assignment statement in a lambda
> function. But:
> 
>  1. one shouldn't warp one's API design to accommodate lambda functions,
>  2. accelerometer.x is read-only,
>  3. I doubt the curriculum for 11-year-olds will include lambda, and
>  4. I propose we strenuously avoid callback-based APIs. ("I don't like
>     callback interfaces, I always get them wrong" --GvR (quote is
>     approximate)) Iteration > callbacks.  For example, Python's
>     sched.Scheduler class has a callback-based API, but the Scheduler
>     class I've written for the micro:bit (coming soon!) does not.
> 
> 
> I'd greatly rather see us make properties of objects behave like simple
> attributes, using descriptors where necessary. I suggest that's far more
> Pythonic--accessor functions always feel like Java or C++ to me. 
> (Indeed, ISTM the descriptor protocol was added to Python precisely so
> we don't ever need accessor functions!)
> 
> It's our API, we can spell it any way we like.  I propose we use simple
> attributes nearly everywhere, using descriptors where necessary. I'd
> reserve the .set_x() accessor method spelling for the rare attribute
> that actively changes something (e.g.
> microbit.display.set_display_mode). And I still might use a read-only
> descriptor instead of a .get_x() method for those. (Though I'd have to
> think about that one, and/or play with some examples.)
> 
> 
> Cheers,
> 
> 
> //arry/
> 
> 
> _______________________________________________
> Microbit mailing list
> Microbit at python.org
> https://mail.python.org/mailman/listinfo/microbit
> 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: OpenPGP digital signature
URL: <http://mail.python.org/pipermail/microbit/attachments/20151030/025ec910/attachment.sig>