Reading Programing Language Specs

By Xah Lee. Date: .

JavaScript spec is the most incomprehensible by far. From my experience, having read part or all spec of: golang 2018, scheme r4rs 1999, racket 2015, emacs lisp †, python, php 2006 †, clojure †, svg, perl †. those † has no spec just doc. ☺

Mathematica, has no spec. It has 1k pages manual. I read cover to cover, word for word, 3 times in continuous setting, in separate years, from 1993 to 1999.

Scheme lisp r4rs, is also the shortest and lean. I read at least 3/4 of it in 1999. But back then, i don't have much lang spec experience. don't understand it that much.

perl, has no spec. It has docs, i read cover to cover several times from 1998 to 2004.

Java lang spec i had some glimpse mostly 2010s. It's professionally written, and unlike W3C's spec nor JavaScript's, it's practical and readable. But the language is fairly complex.

PHP has no lang spec. (at least during 2010s). I read basically the entire doc in 2006, doing a project. It is, the most easy-reading, understandable.

JavaScript spec i read basically all, of multiple versions of it. ES2015 one is the most incomprehensible. The version before: 〈2011 ECMAScript Language Specification - ECMA-262 Edition 5.1〉 is itself worse than all others lang specs. ES2015 doubled the size and complexity. Note, complexity of spec is not necessarily due to lang complexity. It's due to the spec writing. Most lousy specs are due to the writing style, bloated words, and in open source projects, often irrelevance and conceit.

SVG spec i read most starting 2015, parts multiple times. As with most w3c dom stuff, it's written in a incomprenhensible semi adacemic semi industrial way. Bloated with jargons and words that pretends to be comprehensive and precise but actually is neither.

Racket scheme lisp. I read parts of the spec around 2015. Doing some homework in racket for someone. lol.

emacs lisp, has no lang spec per se. It's 1k pages manual, i read some 70% over the decade since 2006.

Python has a semi spec. They call the “language reference” section in the doc. Full of imprecision, conceit, irrelevance. Python folks always trying to sell you something, with passive aggression.

Clojure, has no spec. I spend close to 1 year full time, spread between 2014 to 2016 reading its doc. (it doesn't really have doc neither. It has doc string, and collection of “essays/concepts”) Extremely dense. It has lots problems, mostly due to intentional mix with Java.

Golang spec is the most concise and precise, and shortest. (comparable and surpass Scheme's spec in concision, precision, and brevity.) I read parts in 2018, and understand it well.

See also: Emacs Idolization: Have You Read the Emacs Manual From Cover to Cover?

more articles on doc, see doc by dummies

If you have a question, put $5 at patreon and message me.