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.
Claus
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
