lexical 'super' in arrow functions?

Claus Reinke claus.reinke at talk21.com
Wed Dec 5 02:04:52 PST 2012

> Language specification is a difficult task, especially when handling a
> complex language, legacy spec style, and wide variety of audience
> background, not to mention a committee with lots of feedback and opinions.
> We are very lucky that Allen does the job he does.

Yes. That doesn't mean he should have to do everything alone,
or that the results of his work shouldn't be useable for a wider
audience. And documentation helps collaboration. Here's an 
illustrative example from another context:

I've recently been digging through non-trivial, insufficiently
documented project source code (namely the TypeScript compiler 
and services). So have several others. Like a spec, the whole thing is 
completely specified by its source, but with just a few more high-level 
comments, we would have had a much easier time, would have 
wasted less time, and would be more certain of the understanding 
we've reached. More coders would have tried or more would have 
succeeded in building on the services, and earlier. There still isn't
as much plugin developer uptake as the code itself warrants.

If you believe in commenting source code, you should believe in
annotating the reference implementation that is the ES spec.

> That also means we shouldn't make it harder, or ask the spec to bear
> burdens it doesn't need to handle.  JavaScript is blessed with numerous
> excellent books describing how to use the language and what various
> features are for, including Dave's new book. That's the place to go for
> description and explanation, not the spec.

I'll try to answer several related concerns in one reply:

1. Back when I last looked at Standard ML, it had a formal definition
    and an informal, but official commentary

    I don't want that - it explains the formalism, instead of the language

2. David Flanagan does a very nice job of providing an informal
    reference to the language (and its environment)

    I hope he'll do it again for ES6, and the ES6 spec should not 
    include all the useful text that he adds

3. There have been community efforts to explain or annotate the
    spec, and I hope there will be such efforts for ES6

    This is getting closer, but represents more work than is needed 
    for documenting the core spec

4. There are concerns about annotations (a) extending the failure
    surface and (b) being used instead of the normative parts

    (a) yes, definitely want that! It is about saying the same thing
        twice, in different forms and level of detail. That means one
        can check for internal consistency, and file either a spec or
        a documentation bug.

    (b) if implementors are tempted to "treat prose as normative",
        that only confirms that the normative formal parts are too
        difficult to interpret for normal JS hackers;

        By all means, put the normative, formal parts first, then call
        the informal parts "notes on the spec", to avoid any genuine
        misunderstandings about which parts are normative; then
        community and tests need to ensure that engines implement
        spec, not notes.

What do I want, then? Well, good comments give intent and big
picture instead of explaining the code. And some parts of the spec
do have both already. So I'm mainly asking for very brief notes
in the existing style (on language features, not on the formalism).

For instance, chapter 8 is all about the big picture, and the return 
(12.9) and with statements (12.10) have short notes explaining 
what they are about. This shows that no huge effort is needed.

    Given that with was well on its way out of the language, and that 
    so many coders do not care about strict mode, there ought to be 
    an explanation that use of 'with' is discouraged, and why (it is 
    useful, but too powerful for its use cases).

However, right before that, the continue (12.7) and break (12.8)
statements have no such explanatory notes. This shows that the
level of documentation is not consistent, and that it is not just a
question of focusing on the formalization of new features first.

Moving to new stuff, the only notes in arrow function definitions
(13.2) are explanations of the formalism, the only notes about
lexical this (never mind lexical super) in arrows are in the sections 
on *.forEach. The super keyword section (11.2.4) has no notes 
at all - if you were browsing the spec trying to figure out what
super is about in JS, how much of the spec would you have to
read to answer that question, and how many readers succeed?

So, I am not asking for great extra efforts, just for a couple of
sentences indicating what each language feature section is
trying to formalize. If the big picture sections exist and are
readable, then simply using language NOTEs consistently 
everywhere would help.


More information about the es-discuss mailing list