Re: Advice on how to best handle a long list of attributes

On Fri, Sep 26, 2014 at 12:28 AM, Anne van Kesteren <annevk@annevk.nl> wrote:
> On Fri, Sep 26, 2014 at 2:29 AM, Jeffrey Yasskin <jyasskin@google.com> wrote:
>> Whatever we do with naming, there's also the stylistic questions of
>> how to expose them:
>> 1) Does the web prefer navigator.foo.bar or window.FooBar?
>
> The latter, classes you can construct over objects that come out of nowhere.

Marcos was suggesting a window.BluetoothUnitMap, with a static .get()
method returning UUIDs. Your advice sounds like you prefer that folks
construct a `new window.BluetoothUnitMap`, and then call .get() on the
result? The initial contents of the map would still come out of
nowhere.

Does your advice also mean that the bluetooth system as a whole should
be a class too, instead of a navigator.bluetooth that comes out of
nowhere? But what would it mean to write `new BluetoothAdapter()`? You
can't construct a new Bluetooth radio in software. You could imagine
having it ask the browser to emulate a new device, but most existing
hardware can't even emulate a new device for each origin, let alone
multiple devices for each origin.

>> 2) Does the web prefer an object with attributes or a Map?
>
> For APIs you typically can't use either directly. So, depends...

I don't understand what that means. We have some root object, either:
1) root_object = AClass;
2) root_object = navigator.foo;
3) root_object = new AClass();
and then that object can expose constants as either attributes or as
the result of methods: root_object.a_constant or
root_object.get('a_constant').

https://www.khronos.org/registry/webgl/specs/1.0/#WebGLRenderingContext
does this as attributes (although with the discouraged WebIDL const
keyword), while Marcos is suggesting we imitate Map's methods.

> https://wiki.mozilla.org/WebAPI/DesignGuidelines has some general tips
> as well as some pointers to more specific advice.

Thanks, although that seems to be aimed at API design strategies,
rather than at explaining which Javascript spelling folks prefer when
there are several options.

> Although the WebGL API is rather sad in places, you could look at it
> for some inspiration as to how to handle mapping to an underlying API
> from JavaScript.
>
> Also, it sounds like you need to embrace the fact that you will have
> to keep updating this specification forever. A specification is
> basically a piece of software in that way. Having it magically
> co-evolve with Bluetooth seems unrealistic (and not necessarily
> desirable, as their design choices might not match the web well).

Right. There's still the worry that if we use different names from the
Bluetooth SIG, developers will be confused about which one to pick, in
the sense of trying to use the one from the Bluetooth docs before
remembering to use our spec instead.

Thanks for the help. I may try to bug Tab in person tomorrow to
iterate a bit more quickly.
Jeffrey

Received on Tuesday, 30 September 2014 01:41:25 UTC