Coffeescript 1.5.0 was released today, and I have to admit that I find the purpose of the release puzzling in the extreme. Jeremy has gone full-on Literate Programming, embedding support for LP-style commentary in the compiler. If there’s one language that doesn’t need Literate Programming, it’s Coffeescript. The example he gives is terrible; it uses verbiage to hide what’s essentially going on.
I have used Literate Programming often in the past, often to explain something difficult either to myself or to others. LP is something I’ve used mostly for pedagogical reasons; using it in actual code strikes me as excess. Either your code is well-designed and highly expressive, or you’re failing it (and it’s failing you) in some way. And as you’ll note from The Backbone Store series, I didn’t need “literate” support in the compiler to create functional, descriptive, and beautiful literate programming documents.
If you want to do Literate Programming, you have many choices choices: Jeremy’s own Docco allows you to create documents-in-source-code, and Norman Ramsey’s Noweb (the tool I used for The Backbone Store) allows you to go the full-on Donald Knuth source-code-in-documents route if you want. This, documentation-by-default choice just seems weird and arbitrary.