While I love Coffeescript and Literate Programming, this puzzles me...

[elfs]

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.

Comments

[elfs.livejournal.com]

No, Literate Programming is far and beyond merely commenting code. It's a discipline in which you tell the "story" of the program as a whole narrative, describing in excrutiating detail every bit of the program, and how it fits together, and where and when it's called. Advanced LP environments, like NoWeb, allow you to write the program out of order, describing an overview and then details, or vice-versa, and then constructing the actual source code out of your narrative before feeding it to the compiler. See the source code to "The Backbone Store (https://github.com/elfsternberg/The-Backbone-Store/blob/master/backbonestore.nw)" for an example: it's written in LaTeX with embedded code blocks. The blocks are in the order I felt necessary to accurately describe the program, not to assemble it. It's the job of the NoWeb assembler to extract and restructure the code for actual compilation and deployment.