Perhaps, although most examples of literate programming that I have run into tend to be so verbose as to be equally daunting and off-putting in a completely different way. Another great topic: the art of the comment!
I prefer to record design decisions not inline in code comments but in my git commit log. Design decisions are best viewed as a chronological big-picture conversation with myself as I try out different things. I also find them to be just concise enough.
Thanks for the link, that's pretty interesting. Do you use a modification of this now, or have you simply codified that approach internally and commit intuitively?
Seems ok. Not sure it's the "answer" to making sense of a codebase, but it's certainly addresses part of the problem. Why do you number your files, e.g. 003parse.cc?
I often run git blame to track down and reread old commit logs. But yeah the new codebase kinda dilutes the point because I'm changing so many things at once. It's an exercise in making a codebase as self-documenting and approachable to outsiders as possible in a variety of ways.
The numbered filenames are one example. Each file is intended to be self-contained, and later files build on earlier ones. No need to hack on makefiles to add a new file. Just create it, number it right, and it'll get compiled, with access to everything in earlier files.
Since this is a lisp interpreter the ethos translates to lisp functions as well. I can improve performance by deleting a lisp function, reimplementing it in a new .cc file, and restarting the interpreter. The interpreter will transparently run make, which will transparently compile the new file. And tests on the lisp function will continue to pass if I did the translation right.
There's a README (http://github.com/akkartik/wart#readme) that tries to convey my goals, but I haven't had too many people read it yet. I'd love to hear what isn't clear. You aren't supposed to know lisp to understand it.