[akkartik]

Narratives in code are a tempting analogy, but code is non-linear. Verbose 'how' code comments usually assume one path through the code, and it only matches my actual path 0.1% of the time. The remaining 999 times out of 1000 all the verbosity just gets in the way.

The best idea to come out of literate programming, IMO: order code in the best possible order for reading and navigating, and let the computer figure out how to compile it. That's one thing we've largely gained from more dynamic languages like python and ruby, and from AOP. That's about it. It's good to to aim for a codebase I can curl up with on my iPad, but if so my interest is in the code. Don't get hung up on typography, and assume I'm going to be choosing my own adventure at the end of each page.

[shahriarhaque]

When you start your source file with a huge chunk of "how" comments it is likely to not match the actual code path. But that's not how I think the "documentation mode" will work. You write how comments for every small chunk of code. Then whichever code path the program executes, you will see a flow of comments from that path