Specifying template strings

Allen Wirfs-Brock allen at wirfs-brock.com
Thu Jul 10 08:37:14 PDT 2014


On Jul 10, 2014, at 7:10 AM, Jason Orendorff wrote:

> On Wed, Jul 9, 2014 at 5:02 PM, Allen Wirfs-Brock <allen at 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


More information about the es-discuss mailing list