Jeremy Ashkenas, creator of CoffeeScript, Backbone.js, and Docco, writes about code documentation and literate programming.
HN commenters cite it for Docco and literate CoffeeScript as examples of annotated-source documentation and for popularizing literate programming.
I'm pretty excited to see some of the first programs that folks might write with this -- I've got one of my own, a little 400 LOC (half of which is comments) static blogging engine that's currently powering http://ashkenas.com.
Part of the idea is that, because first and foremost you're writing a document describing what you're doing, and then filling the the implementation in the gaps ... you end up structuring the program differently than if you started out with the code was at the top level, as usual. For me, it was a fun process -- start with an outline, expand that into paragraphs below, then indent four spaces and implement each paragraph...
I'll share the full bit when I make it out of the woods next week, but for now, here's a sneak peek of a rough draft to give a flavor: http://cl.ly/N8Kx
Edit: If anyone wants a copy of the hybrid Markdown/CoffeeScript syntax highlighter (for TextMate or Sublime Text), it's available here in the "Syntaxes" folder. https://github.com/jashkenas/coffee-script-tmbundle 10,000 bonus points if you port it over to Pygments and send a pull request to GitHub ;)
I think literate coffeescript might be a better example of popularizing literate programming:
http://ashkenas.com/literate-coffeescript/
There also seems to be some traction for literate Haskell:
http://www.haskell.org/haskellwiki/Literate_programming
I experimented a bit with literate programming on an introductory course in programming using java. It's an interesting experience -- it's very easy to produce a very readable language that is still pretty poor java code, as it becomes so easy to split out fragments and "procedures", rather than follow the more common java class-oriented object orientated way of doing things.
if:
in_ruby=i=o=
gets();taken_care_of_by_a=
function_like = puts(i)
(from http://web.colby.edu/jasperry/2011/11/10/a-ruby-haiku/)
and:
Haskell is concise
Functional well-typed and neat
It is like Haiku
(from http://www.haskell.org/haskellwiki/Haiku)
and:
Journo is coffee's
literate publishing app
terse prose, wordy code
(inspired by http://ashkenas.com/literate-coffeescript/)
...then why is terse programming less expressive
and terse literature more expressive?
I'm surprised no one has mentioned Literate Programming[1]. It's a concept where comments should reflect the programmer's intentions, explain why, not what is going on, intertwining text and code.
It lives on in CoffeeScript and tools like Docco. The just-released Coffeescript 1.6 supports a mix of markdown and code that looks great: http://ashkenas.com/literate-coffeescript/
[1] http://en.wikipedia.org/wiki/Literate_programming
I'm intrigued by the concept of literate programming and interested in exploring options for a Scala project I'm working on right now. It looks like this one was done using Docco [1]. Docco supports Scala, and it appears to be a pretty lightweight approach, largely using Markdown. I'm curious whether any literate programming veterans have tooling they prefer?
[1] http://ashkenas.com/docco/
Side note - it's been a while since i've seen a Docco-style annotated-source-style documentation! http://ashkenas.com/docco/
Backbone.js was the first time i saw it, and I loved it! https://backbonejs.org/docs/backbone.html It demonstrated to me that the libraries I use are just normal code that other people write, and i myself can read it to understand a problem.