Why is there a large difference in readability between the C# and ECMAScript specifications?

Question

I have been studying the ECMAScript specification and have found that it is extremely hard to read and understand. I constantly have to backtrack to keep concepts in my head. When reading the C# specification I am able to study components of the language without constantly moving around the document.

ECMAScript Specification

C# Specification

Answer 1

As I am the only person regularly posting on SO who has been a member of both the C# language design committee and the ECMAScript technical committee, I can probably offer a few insights.

First off, thanks for your kind words about the C# specification. We've worked very hard to keep it readable and it is good to know that we've succeeded.

Second, I note that the C# specification was not always that way. The C# 2.0 specification was written as an addendum to the C# 1.0 specification. Generics, iterator blocks and anonymous methods had widespread impacts on many sections of the specification. It was a real pain reading the 2.0 spec and having to jump around between two chapters to understand the real overload resolution algorithm. Mads did a huge amount of editing work in C# 3.0 to first integrate all the C# 2.0 changes into a reasonable place in the spec so that you would not have to jump around all over the place.

Third, a big part of what you're describing is a result of differences in both goal and style of the principal architects of the two specifications. Imagine a spectrum of "technical-ness" with papers about formal correctness written largely in Greek letters at one end, and magazine articles for beginners on the other. We design the C# specification to fall at a particular place on that spectrum. We do not want it to be a beginner programmer tutorial, but do want it to be a reasonable document for beginner C# programmers to consult. Anders specifically wished to avoid what he calls "the higher math of the specification".

This is a reasonable set of goals given our target audience for the spec: professional programmers, some of whom want to learn C#, and some of whom want to look up precisely how something works. The spec has vague tutorial aspects and precise semantic description aspects in order to serve those two constituencies.

Waldemar Horwat, the principal author of the ECMAScript 3 spec, had rather different goals for the E3 spec -- not worse goals, but different goals. The goal of the E3 spec was to be far more towards the mathematically precise end of the spectrum. You'll note how practically every section of the specification consists of essentially pseudocode algorithms that describe in rather math-heavy prose precisely what the effect of each operation is on the system.

You'll notice for example that the E3 specification talks about the difference between "mathematical" numbers and their binary representations. One draft of the E4 spec even went so far as to note that there are set-theoretic problems with a naive definition of "type" as a set of values if types are also values. This sort of thing would be completely out of place in the C# spec; it does not seek to have a strong theoretical mathematical underpinning to ensure its correctness. You'll note that the C# spec nowhere even defines "type" -- it was written with the assumption that the readers will be pro devs who (1) already know what types are for practical purposes, and (2) neither know nor care what set theory or category theory has to say about the mathematical well-foundedness of any definition of "type".

The goal of the ECMAScript process was for multiple vendors of highly similar languages to come together and agree on a precise description of what was in the common ground amongst all those implementations. The E3 spec was never intended to be a tutorial of any kind, and is primarily aimed at language and tool implementors, rather than language users.

Waldemar's E4 spec went even further. If I recall correctly, he began by specifying a very precise, simple "spec language" with clear semantics. Then he wrote an interpreter for that language in Common Lisp. Then he wrote the E4 spec in his spec language. The result was that he could compile the specification itself into a working ECMAScript interpreter. That is exactly the sort of "higher math" that we are trying to avoid in the C# specification. This is an awesome approach to specification if you want to be incredibly precise and accurate, but it is a terrible way to write a document that language users can learn from.

Does that answer your question?

Answer 2

You are probably experiencing a difference between the readability of the specifications of the two languages because they were written by different groups of people, and discuss languages which employ different object paradigms.

The JavaScript specification was written by a committee after the language had evolved organically after several years. The C# specification was written by a small group of corporate engineers while the language was growing in a controlled manner.

C# is class-centric OOP and JavaScript is prototype-centric. It is possible that if you are not as familiar with one as you are with the other, then some material may be difficult to understand at first, especially when it gets into implementation details. That doesn't necessarily indicate a problem with the clarity and readability of a specification.