Don’t just write comments, tell a story

Otherwise known as Literate Programming with an IDE. :-)<p>The general problem with this is that code changes too rapidly for documentation to be of any use. Writing the documentation for code can easily take 2-3 times longer than writing the code itself, so if you're iterating at all, that documentation will probably be about 5 revisions out of date. At that point, it's actively harmful, because it tells the reader things that are wrong.<p>It works great for TeX, not so well for a startup that will have a new business plan in a couple months. That's also why the best comments tend to be API docs: APIs change (or should change) much less rapidly than implementation, so the documentation is both more useful and has less chance of being out-of-date.

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.<p>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 <i>code</i>. Don't get hung up on typography, and assume I'm going to be choosing my own adventure at the end of each page.

I think that's really cool! Next step: parse those stories using a BDD framework! Looking at that interface brings to mind something like lettuce.it<p>You could parse out the comments into a separate story block then write in the features/notes from lettuce and have them link back to each chunk of the code - providing coverage reports and the like.<p>Now it just needs a vim plugin ;)

Docco is cool. Is there an online version of it, to give it a try?