[Microbit-Python] Flat API

[Michael]

Added to the wiki page :)


Michael.

On 22 September 2015 at 13:33, Matthew Else <matthewelse1997 at gmail.com>
wrote:

> If I think back to the time that I first learned to code, which would have
> been when I was younger than the kids using the micro:bit, I feel like .p0
> could feel like some sort of special syntax in the same way that square
> brackets can seem confusing to kids learning to code. I suppose this goes
> along with the idea that abbreviations are bad in this context. As a result
> I feel like even this could reduce confusion, by simply having this:
>
> from microbit import pins
>
> pins.pin0.digital_write(1)
>
> pins.pin0.analog_write(0.5) or pins.pin0.analog_write(128)
>
> pins.pin0.digital_write(0)
>
> print(pins.pin0.digital_read())
>
> print(pins.pin0.analog_read())
>
> i.e. Having pinX instead of pX.
>
> On Tue, Sep 22, 2015 at 12:50 PM Michael <sparks.m at gmail.com> wrote:
>
>> Good API design for children though is not the same as good API design
>> for everything. For many children, I expect that this ...
>>
>>     microbit.pins.p0.write_digital(x)
>>
>> .. will read as  "microbit pins p0 write digital x", and they'd wonder
>> "Why are the words in the wrong order?", which would suggest they would
>> prefer something that reads like "microbit write digital pin 0 x".
>>
>> Whether this is flat, or not, whether the words are separated by "." or _
>> , is almost irrelevant. To a child, there's NO difference at all. (I know
>> there is in practice, but to them BOTH are just noise, which results in the
>> words being in the wrong order here)
>>
>> It's also worth bearing in mind that at KS3 at school children aren't
>> taught object orientation (it's not in the curriculum), so this could
>> easily be confusing. Especially for a first introduction.
>>
>> To me that almost suggests the opposite of normal:
>>
>>     microbit.write_digital_pin_0(ON)
>>
>> That's pretty gratuitious, but inherently *clearer* if you are 11. (just
>> based on working with cubs and scouts, so limited experience, but some)
>> From an implementation perspective this might may more sense:
>>
>>     microbit.write_digital_pin(0, ON)
>>
>> That then has the risk they'll put duff values in for pin numbers though.
>> Now making errors is part of coding, so I'm not averse to it on that basis,
>> but out of these two options, the former increases the chance of success,
>> which I think is a good rationale for a decision.
>>
>> The only other point I'd make is in this thread write/read and set/get
>> have been used, and I'd suggest that one and only one of those gets used.
>> IMO, set/get make more sense:
>>
>>     microbit.set_digital_pin_0(ON)
>>
>> Remember, the API isn't designed for developers or teachers, but for 11
>> year olds - of all abilities - many of whom will have reading and writing
>> difficulties. So while as you say this isn't code golf - trying to find the
>> absolute shortest way of writing something, being brief *if possible*
>> matters. At least 1/2 can't spell well at this age - which probably means
>> auto-completion really matters here. (For me that's also the reason short
>> and sweet is a good idea).
>>
>> </tuppence>
>>
>> It'd probably be useful to capture all this in a document we can all
>> edit/view rather than just in email. Seeing what the suggestions look like
>> is clearer then. Even just a page editted directly on github. (I'm not sure
>> where would be the place where everyone could see - otherwise I'd just
>> create one :-)
>>
>>
>> Michael
>>
>> On 22 September 2015 at 12:09, Larry Hastings <larry at hastings.org> wrote:
>>
>>>
>>>
>>> On 09/22/2015 01:19 AM, Michael wrote:
>>>
>>>
>>> microbit.pins.pin0.set_digital_value(1)
>>>
>>>
>>> Actually where we left it yesterday, this would be spelled
>>>
>>> microbit.pins.p0.write_digital(1)
>>>
>>>
>>> dpin0 = True
>>>
>>>
>>> I don't like this API.
>>>
>>> First, I don't think the kids are going to make loads of use of the
>>> pins.  Certainly not on the first day, or I suspect even the first two
>>> weeks.  They'll play with things that are easy and fun, presumably the two
>>> buttons and the display, and start learning programming concepts like
>>> variables, functions, and flow control.  It's okay if infrequently-used
>>> things are slightly longer to spell.
>>>
>>> Second, I definitely came around on the idea that pins are more like
>>> sockets and less like values.  Hiding it behind a property is misleading,
>>> and as such is a disservice to the user.
>>>
>>> Third, There Should Be One--And Preferably Only One--Obvious Way To Do
>>> It.  I'm not supportive of having a second shorter spelling just 'cause
>>> it's shorter, and I'm definitely supportive of replacing the API we
>>> hammered out yesterday with abrupt names like this.
>>>
>>> Fourth, as we were admonished yesterday, abbreviations are a no-no.
>>> They're confusing for non-native-speakers of English.
>>>
>>> Fifth, if the user is making frequent use of pin 0, they can make their
>>> own abbreviation:
>>>
>>> import microbit as m
>>> def dpin0(x): m.pins.p0.write_digital(x)
>>>
>>> And thus learn something--and feel clever!--in the process.
>>>
>>>
>>> Good API design is not code golf, trying to find the shortest possible
>>> way to spell something.  Nor should an API try to be all things to all
>>> people.  Rather, a good API should be concise without sacrificing
>>> readability.  I remind you of the old maxim that we spend far more time
>>> reading code than we ever spent writing it.  That will be especially true
>>> of the kids, whose will have much more trouble getting their first programs
>>> to work than any of us did.
>>>
>>> Let's not be PHP, where there's one flat namespace for all functions.
>>> But we don't have to be Java either, where four or five dots in a package
>>> name is not uncommon.  Python frequently inhabits a happy medium, and I
>>> think what we had on the board yesterday found this happy medium too.
>>>
>>>
>>> */arry*
>>>
>>> _______________________________________________
>>> Microbit mailing list
>>> Microbit at python.org
>>> https://mail.python.org/mailman/listinfo/microbit
>>>
>>>
>> _______________________________________________
>> Microbit mailing list
>> Microbit at python.org
>> https://mail.python.org/mailman/listinfo/microbit
>>
>
> _______________________________________________
> Microbit mailing list
> Microbit at python.org
> https://mail.python.org/mailman/listinfo/microbit
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.python.org/mailman/private/microbit/attachments/20150922/bc2826bf/attachment-0001.html>