Opening a nicely documented source file is like opening a well-designed, nicely printed book. The main text is obvious, but the side-notes are there to help you when you aren’t quite catching where the author goes or when the author wants you to go read up on something else for context.
Opening a file that needs few comments is like opening a notebook. It’s the raw form of an idea. A few people can pull this off, distilling a program down to its essence.
Both are charming in their own way. The challenge is to know when you’re producing a book and when you’re writing in your notebook. Write for yourself first, then edit it up or down for the reader.
