Re: [whatwg/streams] Clarify some of the ECMAScript conventions applied (#790)

ricea approved this pull request.



> @@ -4548,15 +4548,22 @@ and similarly, closing or aborting the <code>writable</code> side will implicitl
 
 <h2 id="conventions" class="no-num">Conventions</h2>
 
-This specification uses algorithm conventions very similar to those of [[!ECMASCRIPT]]. However, it deviates in the
-following ways, mostly for brevity. It is hoped (and vaguely planned) that eventually the conventions of ECMAScript
-itself will evolve in these ways.
+This specification uses algorithm conventions very similar to those of [[!ECMASCRIPT]], whose rules should be used to
+interpret it (apart from the exceptions enumerated below). In particular, the objects specified here should be treated
+as <a href="https://tc39.github.io/ecma262/#sec-ecmascript-standard-built-in-objects">built-in objects</a>. For example,
+their <code>name</code> and <code>length</code> properties are derived as described by that specification, as are the
+default property descriptor values.
+
+We also depart from the [[!ECMASCRIPT]] conventions in the following ways, mostly for brevity. It is hoped (and vaguely
+planned) that the conventions of ECMAScript itself will evolve in these ways.
 
 <ul>
   <li> We use destructuring notation in function and method declarations, and assume that the destructuring assignment
     procedure was performed before the algorithm starts.

Should we say "algorithm" rather than procedure? I was surprised when I was trying to reimplement it for #777 that there are some subtleties involved. (I have since abandoned the approach of trying to reimplement it in spec language).

> @@ -4548,15 +4548,22 @@ and similarly, closing or aborting the <code>writable</code> side will implicitl
 
 <h2 id="conventions" class="no-num">Conventions</h2>
 
-This specification uses algorithm conventions very similar to those of [[!ECMASCRIPT]]. However, it deviates in the
-following ways, mostly for brevity. It is hoped (and vaguely planned) that eventually the conventions of ECMAScript
-itself will evolve in these ways.
+This specification uses algorithm conventions very similar to those of [[!ECMASCRIPT]], whose rules should be used to
+interpret it (apart from the exceptions enumerated below). In particular, the objects specified here should be treated
+as <a href="https://tc39.github.io/ecma262/#sec-ecmascript-standard-built-in-objects">built-in objects</a>. For example,
+their <code>name</code> and <code>length</code> properties are derived as described by that specification, as are the
+default property descriptor values.
+
+We also depart from the [[!ECMASCRIPT]] conventions in the following ways, mostly for brevity. It is hoped (and vaguely
+planned) that the conventions of ECMAScript itself will evolve in these ways.
 
 <ul>
   <li> We use destructuring notation in function and method declarations, and assume that the destructuring assignment
     procedure was performed before the algorithm starts.
   <li> We similarly use the default argument notation <code>= {}</code> in a couple of cases.

Maybe link to the algorithm? I found the interaction in the TransformStream constructor surprising when I looked at it. ie. writableStrategy and readableStrategy are defaulted to undefined, which is not an acceptable value for destructuring assignment, and then when the {Readable,Writable}Stream constructors are called those undefined values are converted to {} by the default arguments there, making the destructuring assignment work.

> @@ -4548,15 +4548,22 @@ and similarly, closing or aborting the <code>writable</code> side will implicitl
 
 <h2 id="conventions" class="no-num">Conventions</h2>
 
-This specification uses algorithm conventions very similar to those of [[!ECMASCRIPT]]. However, it deviates in the
-following ways, mostly for brevity. It is hoped (and vaguely planned) that eventually the conventions of ECMAScript
-itself will evolve in these ways.
+This specification uses algorithm conventions very similar to those of [[!ECMASCRIPT]], whose rules should be used to
+interpret it (apart from the exceptions enumerated below). In particular, the objects specified here should be treated
+as <a href="https://tc39.github.io/ecma262/#sec-ecmascript-standard-built-in-objects">built-in objects</a>. For example,
+their <code>name</code> and <code>length</code> properties are derived as described by that specification, as are the
+default property descriptor values.
+

I think it would be nice to explicitly mention the fact that missing and surplus arguments are treated as per ECMASCRIPT function conventions. Although this is implied, it clearly surprises some people.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/790#pullrequestreview-61408941

Received on Friday, 8 September 2017 04:26:33 UTC