Continuing woes in reading the ES6 spec language

Jason Orendorff jason.orendorff at gmail.com
Wed Sep 11 15:28:07 PDT 2013


On Sep 10, 2013, at 5:38 PM, Oliver Hunt wrote:
> The current spec layout seems to be a substantial regression in terms of
> usability vs. the old spec.

Allen, here are a few concrete usability concerns that I think could
be addressed... it just takes time. :-|

 1. In the ES6 drafts, as opposed to ES5:

      * many more algorithms do not have unique names.

      * more sections contain a lot of algorithms (for example,
14.1.1.2 contains 13 implementations of 5 different methods).

      * more algorithms have names that are multiple words, like
"Binding Initialisation" (with a space between, as opposed to
"ToString", "GetValue", "CheckObjectCoercible").

    These things combined have made it harder for me to talk about the
spec with others in practice. Just reporting a bug in an algorithm
requires figuring out how to refer to it.

    Our implementation has comments like:  `// ES5 8.12.9 Step 1`.
There is no similarly concise way to refer to some ES6 algorithms.

    Proposed fixes:

      * Give every algorithm (that is, every list of steps) its own
section heading and/or its own unique name. There will be a lot. It's
worth it. Ideally, we'd have a systematic naming scheme
("OrdinaryFunction»[[Call]]",
"FormalParameterList#3»BindingInitialization" since
FormalParameterList has multiple productions)

        These names could live in the document’s margins or something,
if making them all section headings is just too much.

      * Run together all multiword method names ("BindingInitialisation").

 2. There is no way to find, for example, all Binding Initialisation
implementations. You can search the document. Having found one
implementation, you can't tell if there are others.

    In ES6 many more methods have multiple implementations, and they
have more implementations on average.

    Also it's not clear whether you're looking at all the
implementations or if there are others, possibly living in distant
sections. Algorithms are not grouped strictly by name
("horizontally"), nor by class/grammar production ("vertically"). It's
a hybrid approach. I can see why. But it's surprising.

    This is a major problem for people trying to read the spec. Right
now, if a step says "Perform Binding Instantiation for lhs..." there
is nothing for "Binding Instantiation" to link to.

   I propose adding a section for each method that has multiple
implementations. This new section would (a) have the name of the
method as its heading, and serve as the link target for all the
method's call sites; (b) explain informally what the method is—its
purpose and roughly what you can expect to have happen when you see
it's being called—and (c) list all algorithms that implement it, with
links (except Evaluation, which has too many implementations to list).
The spec currently does this, for some methods, using tables (Table 4
and Table 5 in 6.1.6.2; and Annex F)—but not all, and the
implementation lists are out of date. I can see this sort of thing
being left until later in the ES6 cycle, but it would be awfully
useful to have (a) and (b) now.

 3. Along similar lines, it would be fantastic if every builtin class
had something like Table 37 — I don't know if a table is the right
format, but just a list of the data properties and an informal
description of what they're for.

    "Show me your flow charts and conceal your tables and I shall
continue to be mystified;" and all that.

 4. Can we rename either PropertyDescriptor.[[Get/Set]] or
Object.[[Get/Set]]?  Maybe PropertyDescriptor.[[GetAccessor]]; or else
Object.[[GetProperty]].

    Not a new issue in ES6. But fixable in ES6.

-j


More information about the es-discuss mailing list