Spec feedback on rev 6

Brendan Eich brendan at mozilla.org
Wed Aug 1 08:11:54 PDT 2012


Herby Vojčík wrote:
> 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.

More to go wrong, in my experience -- more spec-bug habitat and 
potential confusion between informative and normative. This happened 
especially with ECMA-357 (E4X), which had more prose and motivating 
examples before the normative spec, where the informative stuff was 
often wrong or misleading.

Specs need illumination by companion docs, hyperlinking/transcluding 
codexes, etc. Another reason for HTML spec format (thanks again to 
jorendorff!).

/be


More information about the es-discuss mailing list