On Jul 10, 2014, at 7:10 AM, Jason Orendorff wrote:
> On Wed, Jul 9, 2014 at 5:02 PM, Allen Wirfs-Brock <al...@wirfs-brock.com>
> wrote:
>>> – Tagged templates are explained via EvaluateCall(tagRef, TemplateLiteral,
>>> tailCall). I think it would be easier to understand if it used
>>> GetTemplateCallSite.
>>
>> Because a Tagged Template is a call. Would it be clearer if there was a note
>> that highlighted the fact that the actual TemplateLiteral provides the
>> argument list for the call?
>
> This is one of many places where the spec would be greatly improved by
> a line or two of explanatory text. Here is an attempt:
>
> -------
> 12.3.7
>
> A tagged template is an expression such as x`the secret words are ${a}
> ${b}`. It looks like a string, but it is a kind of function call. It
> is evaluated like x(callSite, a, b) where callSite is a call site
> object (see 12.2.9.2.2), an Array of strings that supplies the textual
> parts of the template.
>
> 12.2.9.2.2
>
> Call site objects are used in the evaluation of tagged templates
> (12.3.7). They contain the string parts of a template. Since this
> information is always the same for any given template, a single call
> site object is created for each tagged template in a program, it is
> frozen to prevent modifications, and it is reused each time the tagged
> template is evaluated.
> -------
Most of this is already in Note 2 of 12.2.9.22 with somewhat different wording.
(but the section reference in Rev25 to tagged templates is wrong).
In general, I'm happy to receive bug reports suggesting the addition of
informative material such as the above. It's one way that I discover where
things need additional clarification. But also see my comments below.
>
> There are so many algorithms with no explanatory text at all that it
> seems like it must be a deliberate style choice. Is it?
Yes. The experience with Ecma-262 (and other standards) is that redundant
descriptive text (whether marked as normative or informative) is frequently
misleading. And any redundancy introduces the possibility of internal
specification inconsistency. Prior editions had more such descriptive text and
there have been several situations where a buggy or incompatible implementation
of a feature was traced back to somebody misinterpreting a vague descriptive
statement rather than following the details of the an algorithm.
In general, we've tried to reduce the amount of such descriptive in the ES6
spec. Often this was done by taking summary descriptions that had formerly
been formatted as normative text and converting them into informative notes.
(This happened most frequently in the descriptions of some of the standard
library methods). Sometimes developers moving fast read the prose and based
upon that assume that they know what they need to implement without fully
understanding the details of the algorithmic specification,.
>
> Speaking as a user of the spec, a little prose can be a big help. In
> regions of the spec that don't have any, I often feel like I'm reading
> uncommented assembly code, reverse-engineering all higher-level
> structure.
I agree. But good informative notes needs to clarify the normative text rather
than just provide redundant and simplified alternative descriptions
But, please file bugs on things like this, and tell me what you think needs
such clarification.
Allen
_______________________________________________
es-discuss mailing list
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
