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