Howard Abrams has a nice post on Literate Programming. By now that’s a fairly hoary subject—the idea dates back to Knuth in the early 1980s—but Abram’s post is nice because it considers how to do this with Emacs and Org mode.
If you’ve been reading Irreal for a while, you know that I really like and use Org Babel all the time. It’s perfect for reproducible research and keeping all your calculations and data with the rest of your report or paper. John Kitchin has really leveraged this idea for his group’s publishing. His publications are generated directly from Org mode with the calculations performed in Org mode code blocks right in the source file.
Another possibility with Org mode and code blocks is to export the code to another file using the tangle command. That way the code can be compiled separately while at the same time appearing as part of the documentation. Since the code source file is generated directly from the documentation, the code and documentation never get out of sync (although the commentary may, of course). Abrams shows how to do this with a nice, easy-to-follow example and then shows both the finished document and the resulting code files (one for the code, one for the tests).
If you’d like to try Literate Programming but want a lighter weight approach than CWEB, give Abrams post a read. It’s really easy to try the method out to see if you like it.