[Microbit-Python] Flat API

[Michael]

In case helpful, I've copied and pasted into a wiki page here:

http://www.sparkslabs.com/share/MicrobitAPI

username: microbit
password: bigbangburgerbar

The contents of:

microbit-micropython/inc/microbit/qstrdefsport.h

Which appears to be where the names for the API are defined.

I've also created a couple of placeholders for allowing edits to say

"Current API"

"XXXX's Proposal"

The former is currently empty, and there are a few XXXX's sections - which
are currently all empty, except one which copies in Alan's suggestion. (or
will have by the time most peole read this)

It's a fairly naff wiki, and if there's a single github repo we all have
access to, I'd prefer to move the page there. But it's something.

This is in part so we can see all of these on one page.


Michael.


On 22 September 2015 at 12:50, 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
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.python.org/mailman/private/microbit/attachments/20150922/4f6749d0/attachment-0001.html>