Allen Wirfs-Brock wrote:
We generally try to minimize tutorial material (eg examples) and redundancy between normative prose descriptions and normative algorithms. Redundant descriptions has historically resulted in internal inconsistencies. We have also seen cases where implementors follow incomplete prose descriptions without referring to the more complete algorithm. For these reasons, I have been converting much of the redundant prose from previous editions into non-normative notes. In general, examples are only used if they seem necessary to clarify some difficult to understand normative point. Sometimes I will insert an example in order to make it clear that some unusual design point is intentional and not a bug in the specification. The spec. generally does not discuss what a feature is good for or how to use it. Having said all that, the spec. doesn't always follow these guidelines. We working on the 6th edition of a fifteen year old document and sometimes older material doesn't follow newer conventions. Cleaning this up is mostly a "if time is available" task.
An idea related to this: ECMA-262 spec has a test suite. It could be beneficial from coder PoV (maybe for other readers, especially reading it for the first time / after long pause, too) to include shortened (table-like, inputs plus desired output) test-cases before the actual algorithm. Though the algorithm would still be authoritative.
Herby _______________________________________________ es-discuss mailing list [email protected] https://mail.mozilla.org/listinfo/es-discuss
