:) Aww, my goal is extremely utilitarian: to explain lisp to non-lispers. Many of the early files have long comments because readers need the most support early on when they're orienting themselves around a new codebase. By the end, you get a feel for how things work and the code gets more self-documenting. If the goal is to convey intent, surely intent can't be uniformly distributed throughout a codebase. It takes a lot more intent to start; once the fundamentals are in place the rest might even get built on autopilot.

Beyond comments I've also been exploring other mechanisms for keeping code readable. I thought hard about file system organization: making it apparent where newcomers should start, and keeping files easy to move around and rename. I spend a lot of time coming up with names, and minimizing the number of names I use, because the vocabulary of a codebase needs to fit in a person's head far more than lines of code. And I write tests.

Having lots of unit tests has an unexpected benefit for readability in the small. Don't understand why this line needs to be so? Try changing it or deleting it, run all tests. Something failed? Ah, it explains a design subtlety I'd forgotten about. Nothing failed? Sweet, dead code. Good names for tests are way more valuable than for functions because of this trick, but sadly most codebases don't have nearly the coverage necessary to make it tick.

In general I'm far more cavalier towards my code than towards my tests. Take away my code if you want, but leave me my tests. That's where all the reproducible value is.

A lot of my goal is to convey global intent. Often, discussion of one part includes interactions with other parts.

What else? Oh yes, I'm not just writing comments in code files, I also have random files with just prose. And I love this quote for conveying the goal of design:

If I look at any small part of it, I can see what is going on -- I don't need to refer to other parts to understand what something is doing.

If I look at any large part in overview, I can see what is going on -- I don't need to know all the details to get it.

Every level of detail is as locally coherent and as well thought-out as any other level.

-- Richard Gabriel, The Quality Without A Name (http://dreamsongs.com/Files/PatternsOfSoftware.pdf, page 42)

I actually tend to be extremely anti-comments, so it was a little eye-opening to go back and notice how much prose I've written on this project. In the end, the goal is a good design, and there are no hard and fast rules. Just do what it takes.