Thanks for the thoughtful response, but I don't think I can say I agree with your conclusion. One example I cited was Knuth's Adventure. Even knowing C well e

Thanks for the thoughtful response, but I don't think I can say I agree with your conclusion. One example I cited was Knuth's Adventure. Even knowing C well enough, I'm not struck by how Knuth's presentation makes it easier to understand in the way he desires. Knuth very much seems to advocate for programs that can be read cover-to-cover (e.g. while, say, sitting in your favorite chair). I think the failure in his literate programs come down to the blindspots he's developed working on his own programs, from having focused so much on the trees in their respective forests. You can see something similar at play in Graham Nelson's struggles to make Inform 7 appropriately "literate", which funnily enough exhibits the opposite of expectations of familiarity with the original implementation language. <http://inform7.com/talks/2020/06/07/narrascope-ii.html http://inform7.com/talks/2020/06/07/narrascope-ii.html> Have a look at this slide in particular: <http://inform7.com/assets/images/NS2/slide036.jpg http://inform7.com/assets/images/NS2/slide036.jpg> Here's an excerpt: "Once The Historian is done, the instructions are passed to Instruction::read, which parses them more fully (see below) and returns an intest_instructions object". It goes on in that style. This is reminiscent of every bad attempt I saw during Java's heyday to ensure that a given codebase was 100% commented. People just end up writing "documentation" that consists of low-level repetition of what the code is doing, but without explaining why it's doing those things, and that why is key. It's the only real reason to be concerned with making sure things are documented. The code itself explains the how (in excruciating detail, even), the selection of identifier names more or less does the job of explaining the what. It's the role of the comments to explain the why, because (crucially) there is otherwise no substitute for this reified in the code itself, unlike the case with identifier names and procedural control flow. From my original notes upon seeing that slide from the Inform 7 talk: > You don't need to tell us that the instructions are passed to `Instructions::read`, which returns an `intest_instructions` object, because if that's true, then we can already see that. This type of documentation contributes nothing except to people who are new to the programming language you're using, but that's not your audience. > The ONLY way to document a program is to understand that almost everything you write needs to be an answer to the question, "What problem existed that led to this piece of code being created?" Your job is not to describe your solution. We already have your solution and can read through it. Your job is to describe the problem(s) for which your program is a solution. Namely, a problem is defined by its constraints. Detail all of those constraints [before ever thinking of telling us how it is you've decided to work with them]. What do you think of akkartik's take on the imperative to effectively communicate whole-program concerns at the global level? <http://akkartik.name/about http://akkartik.name/about>