Ask HN: Which programming language has the best documentation? | Hacker News Reader

Ask HN: Which programming language has the best documentation?

6 pointszoowar12 comments

Recently I was playing around with Scala/Lift and found the online documentation horrible. It was mostly auto generated function specifications with very little background information. Which programming language has the best documentation?

View on HN

The Java standard library docs are very good, and the language spec is quite clear and precisely defined.

Another language with brutally specific docs is Common Lisp. Even though I have really only dabbled in it, the Hyperspec is really pretty impressive.

At least one common factor between them is Guy Steele, I don't think that's a coincidence.

Edited to add that I'm pretty sure my comment was motivated by this comment by mahmud: http://news.ycombinator.com/item?id=1661254

I remember reading that Guy Steele was specifically hired to the Java project for this reason. Wikipedia corroborates this: "In 1994, Steele joined Sun Microsystems and was invited by Bill Joy to become a member of the Java team after the language had been designed, since he had a track record of writing good specifications for existing languages."

He also documented ECMAScript 1, which I've found to be pleasurably precise.

It depends on how narrowly one defines "documentation" and what one means by "best."

I.e. there's probably a book on Visual Basic that's a good fit for just about anyone's level of interest and programming experience...assuming of course that one has an interest in Visual Basic.

On the other hand, K&R is a concise and well written.

Yet one has an inexhaustible supply of JavaScript examples only an F12 away.

When you answer, you get to define the scope.

In addition to documentation, I find a language specification useful. Golang has an excellent one http://golang.org/doc/go_spec.html My original Stroustrup C++book included a language specification which was nice.

I like both python http://docs.python.org/modindex.html and golang http://golang.org/pkg/ best.

also the PEPs for Python: http://www.python.org/dev/peps/

I'm going to vote twice:

1) ECMAScript, for being excrutiatingly detailed. Guy Steele did a wonderful job shoehorning an unambiguous specification around a loopy language. 2) PostgreSQL. While not particularly mathematical, Postgres docs do a good job of "covering all the bases"... potential "gotchas" and incompatibilities are always documented, and I never find myself wondering what a particular feature does.

The Racket Guide [1] and Reference [2] are very nice (and almost all the work of just one person, Matthew Flatt).

[1] http://docs.racket-lang.org/guide/ [2] http://docs.racket-lang.org/reference/

In my experience I've been trying to learn beginner programming with Ruby on Rails. I feel like there are tons of high quality resources for Python that I come across. Ruby on rails documentation seems pretty good. Ruby documentation though has been tough to find.

PHP via http://php.net/function

C ISO/IEC 9899 - 1999 Standard is my favourite piece of documentation.

Reply on news.ycombinator.com