We did something similar we did when the company I work for specialized in consulting, back in the late '80s. At the end of a project, one of our deliverables was usually something we called "left hand pages".<p>It consisted of a binder with a complete listing of the source code we produced for the client, with the source code printed on the right hand pages. On the left hand pages was a detailed commentary and explanation of the corresponding right hand code. Extra space would be inserted in the right as necessary to make room for the left hand commentary. We would not skimp on the left.<p>The commentary was aimed at being all a new programmer at the client would need to take over maintenance and enhancement of the software. It was assumed he knew the language, and had a copy of and understood the hardware specs. Of course, hardware specs often deviate from what the hardware actually <i>does</i>, and we'd cover all those oddities and deviations in the left hand pages.
Literate programming, at least at Knuth defines it, includes some aspects which Docco omits.<p>Firstly, the machine readable file can be output in a different order than the human readable. (Indeed, sequential chunks in the human readable output can be directed to multiple different files.)<p>Secondly, the human readable file includes 'outlining': when describing a function, parts of it can be elided and covered later.<p>Now, these may have been required because the target language was C(like), which has different properties from many other languages. But I did want to point out that Docco is a quite different point in the literate programming landscape.<p>For examples, see a couple of literate programs that I've written.<p>With Web (Knuth's tool): <a href="https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pdf" rel="nofollow">https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pd...</a><p>With my own tools: <a href="http://www.imperialviolet.org/binary/lsmsb.html" rel="nofollow">http://www.imperialviolet.org/binary/lsmsb.html</a>
One of the more unique programming approaches I've come across is the Leo editor, which was written to support literate programming but also functions as an outliner.<p>When you're working with Leo, you work with a tree of text nodes instead of working with explicit files/directories. Because the nodes exist in an always visible tree, the natural inclination is to label the node with what the code inside does. This subtly enforces literate programming.<p>This is good, but what makes Leo novel is the nodes can be cloned (think hard symlink) and then rearranged however you like. You can put a node containing a function's unit tests and another containing its documentation as children of the node containing the function. When fixing a bug, you can create a node that points to the issue's url in your bug tracker and then clone all related nodes as children for both documentation and convenience when you're working on the bug. When working on frontend code, you can clone nodes for related js/html/css for conveniently switching between them. It's very cool.<p>Unfortunately, it's not really practical to use it as your primary editor. Ed serializes/deserializes the nodes to files using sentinels in comments, so the output files tend to wind up with a lot of "junk" comments. I also missed the Vim command grammar a lot.
For folks wondering about what the "CoffeeScript is about to get <i>even more interesting</i>" bit is about, it's just the past month of changes since 0.9.4, which are considerable indeed:<p><a href="https://github.com/jashkenas/coffee-script/compare/0.9.4...master" rel="nofollow">https://github.com/jashkenas/coffee-script/compare/0.9.4...m...</a><p>If this article inspires you to get started, and you don't mind doing a little bit of legwork to figure out syntactic changes, I'd recommend starting with master instead of 0.9.4.
This isn't actually literate programming as Knuth defines it (If you read his 1984 paper, he specifically talks about _writing the code in such as way as to inform the programmer about what you want the computer to do_, which means that you write the code and documentation at the same time.<p>In addition the literate programming tools that came from Knuths original all allow you to order the in the order you find makes sense -- not in the other required by the compiler.<p>This, while very interesting, is much, much closer to Elucidative programming[1], which is less well known but is also properly easier to get started with.<p>[1]<a href="http://www.cs.aau.dk/~normark/elucidative-programming/index.html" rel="nofollow">http://www.cs.aau.dk/~normark/elucidative-programming/index....</a>
Jeremy Ashkenas (creator of Coffeescript and of docco) is uniquely positioned as an expert in accessible technology.<p>See his hypertext visualization of his thesis project or the various visualizations of government data in his portfolio. He works at DocumentCloud on similar themes.<p><a href="http://ashkenas.com/" rel="nofollow">http://ashkenas.com/</a>
A new <i>implementation</i> of a way to think about programs may be a more accurate title. Quite enjoyed the article though, plus anything giving coffeescript love has my vote.
If an exception is thrown in a Coffeescript program, does the runtime correctly report the original Coffeescript line numbers instead of that of the compiled Javascript? Things like this are the main reason why I'm wary of compilers that compile to another high-level language.
I'd seen a few of these pages before, but never known what they were called.<p>I've also heard of literate programming, but never given it a real shot. Combine that with a recent effort to write more, and this all seems right up my alley. Super cool.
The pseudocode programming process (PPP) described in Code Complete strikes me as quite similar to the concept of literate programming.<p>In PPP the idea is to start with pseudocode in the form of source code comments that start with a very high-level overview of the task being accomplished, written in plain English (or whatever human language), which is then broken down into smaller and smaller constituents.<p>When the explanation can no longer be decomposed, the actual code is written.<p>That approach seems like it would suit the literate programming style very well, and in particular would make the documentation generated by Docco easy to read and comprehensive.<p>That said, I've never really used PPP and prefer TDD instead.
"Going from Javascript to Coffeescript today feels a lot like going from Java to Ruby felt to me in early 2003."<p>One should really wonder, why did he skip on Python, Perl and Ruby for all those years? Knowing that RoR appeared in 2004, and thinking that Coffeescript seems closer to Python