Several months ago I started working with a commercial code base that has about 3 years of commits and over a dozen contributors, but very few inline comments. Navigating and refactoring it is usually a fairly reasonable process due to well-named symbols, module organization, and test cases.
When that's not enough though, I pull up the "git blame" history in my editor, and a rich story unfolds, telling me things like about how old a block of code is, how recently that one line in the middle was changed, and why that seemingly benign extra bit of code is sitting there. Sometimes the commit messages aren't as detailed as one might prefer, but you can often still get a lot of useful insight just from the date stamps.
I've been liking how Visual Studio's CodeLens (now available in cheaper SKUs in 2015) brings focus to commit history specific to logical units in the code (methods and classes).
Now I'm curious where you might be able to push things if you purpose built a "Literate Revision Control" tool and what sort of strong "epic poem" style of commit messages would best produce useful "novelizations" of a codebase...
Perhaps the above would be less useful for more traditional code. Could you describe in more detail how you used it?
I have a long catalog of improvements I'd like to see made to Leo (e.g., its XML file format is version control hostile - try resolving merge conflits on several thousand lines of deeply nested machine-targeted XML; or try sending a pull request slathered with "sentinels"). Building such tools being out of scope for my day job, my re-imagined version won't be available any time soon.
First of all, there were some encoding conflicts that were introduced when mixing Leo with other editors. When I go back to the project now, it doesn't compile because of the encoding errors. (It's fixable, I'm sure.)
Second, I had more classes than I needed. The secret to writing compact game code is - basically - to write few real classes and rely on plain old data and a large main loop. As it was, they were calling up and down some hierarchy, splitting pieces of the main loop into different classes, running a custom scripting language to drive AI, etc. I had all sorts of ill-considered ideas at the time and no real guidance. It wasn't a _tremendous_ amount of code(running a simple count again, 31,145 LOC with whitespace/comments and 22,372 without), and Leo documented what it all did, but the tool couldn't suggest why it was fundamentally rotten, it just added process on top. By the end I wasn't really using Leo, because it wasn't solving my problems.
Looking back on it now, I have a style that can more naturally accommodate a literary programming approach because I'm more likely to write a straight-line solution first. But I would not rely on an external tool again as I don't want the dependency.
I also love the juxtaposition of this comment and the other top comment.
Yes! If your source code files, version control commits, code review comments on those commits, and bug discussion threads are all cross-referenced in a unified Web interface, many problems just go away. IMO it solves the same problems that literate programming was supposed to solve, but less intrusively and more reliably.
Also I agree that code organization is often a bit overrated. I really like linear "hack hack hack" code, even if it has a bit of copy paste, and dislike highly abstract OO soup. On the flip side, I happen to be fanatical about good naming, which is easier if the code is more concrete than abstract.
If your code consists of a lot of DSLs, clearly separated from each other, each implemented in a small, compact, readable module - then you won't have to change that much in the existing code. In my experience this style is a very good match for a literate programming.
We have an alternate method of understanding how software developed, which is to look at revision control commits. This method falls more in line with the techniques of development and the genuine evolution of the codebase. Recall that revision control methods were still being improved well after Knuth wrote about literate programming, and the available systems, where people used them(and a lot of shops didn't), weren't nearly as fine-grained back in the 1980's.
Personal experience: I tried using "Leo", an outlining and literate programming text editor, for a project. Although the documentation capability was nice temporarily and gave me an additional method of structure and organization, the hooks messed around with some formatting and refactoring operations, and most of the time, the benefit wasn't clear. The time I spent on the documentation could have gone - from my current perspective - into making the code smaller and simpler. At the time, I didn't know how that would be possible, thus I focused on defending against the complexity by adding more.
A lot of our preconceptions about what makes code both look good and behave well are temporary. That makes it hard to come up with a sensible system of organization, as we'll put effort in to enumerate and categorize only to discover that it falls apart.