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

[Damien George]

Hi all,

A long discussion!  Some remarks below.

> The other technological problem it raises: we could no longer use attributes
> on the pin0 object.  For example we could no longer say:
>
> microbit.pin0.set_digital_mode(True)

The way it currently works is: pin0.read_digital(),
pin0.read_analog(), pin0.write_digital(x), pin0.write_analog(y).  So
if you wan't to go down the property route, it'd translate to:

pin0.digital_value # get
pin0.digital_value = 1 # set
pin0.analog_value # get
pin0.analog_value = 123 # set

That's not too bad.  But then how about pin0.is_touched() ?
pin0.touched_value as read-only property seems awkward.

And then pin0.set_analog_period()... does it become pin0.analog_period
= 123?  It's going to be a fine line between deciding whether
something is a function or property, and then if some are functions
and some properties that requires effort remembering, and time
teaching.

> My final argument is subjective.  I'll remind you that at the PyCon UK
> sprints I was actually arguing for this exact thing--that you should set the
> value of pin0 by saying microbit.pin0 = True or what have you.  But I was
> convinced to change my mind.  What did it was, again, citing the rule of
> thumb for when to make something a property: it shouldn't feel like it is
> doing something.  A property should behave like a passive object.

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.

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.

Also, consider the button API: do we want button.value as a read-only
property?  What about button.was_pressed()? [this method checks if the
button was pressed since last time, and resets the flag]  It would be
difficult explaining to an 11yo that have button.value is a property
while button.was_pressed() is a method.

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.

Cheers,
Damien.