Interview Transcript – Donald Knuth [pdf]
Thanks for the thoughtful response, but I don&#x27;t think I can say I agree with your conclusion.  One example I cited was Knuth&#x27;s Adventure.  Even knowing C well enough, I&#x27;m not struck by how Knuth&#x27;s presentation makes it easier to understand in the way he desires.<p>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&#x27;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&#x27;s struggles to make Inform 7 appropriately &quot;literate&quot;, which funnily enough exhibits the <i>opposite</i> of expectations of familiarity with the original implementation language. &lt;<a href="http:&#x2F;&#x2F;inform7.com&#x2F;talks&#x2F;2020&#x2F;06&#x2F;07&#x2F;narrascope-ii.html" rel="nofollow">http:&#x2F;&#x2F;inform7.com&#x2F;talks&#x2F;2020&#x2F;06&#x2F;07&#x2F;narrascope-ii.html</a>&gt;  Have a look at this slide in particular: &lt;<a href="http:&#x2F;&#x2F;inform7.com&#x2F;assets&#x2F;images&#x2F;NS2&#x2F;slide036.jpg" rel="nofollow">http:&#x2F;&#x2F;inform7.com&#x2F;assets&#x2F;images&#x2F;NS2&#x2F;slide036.jpg</a>&gt;  Here&#x27;s an excerpt:<p>&quot;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&quot;.<p>It goes on in that style.  This is reminiscent of every bad attempt I saw during Java&#x27;s heyday to ensure that a given codebase was 100% commented.  People just end up writing &quot;documentation&quot; that consists of low-level repetition of what the code is doing, but without explaining <i>why</i> it&#x27;s doing those things, and that <i>why</i> is key.  It&#x27;s the only real reason to be concerned with making sure things are documented.  The code itself explains the <i>how</i> (in excruciating detail, even), the selection of identifier names more or less does the job of explaining the <i>what</i>.  It&#x27;s the role of the comments to explain the <i>why</i>, 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:<p>&gt; You don&#x27;t need to tell us that the instructions are passed to
`Instructions::read`, which returns an `intest_instructions` object, because
if that&#x27;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&#x27;re using, but that&#x27;s not your audience.<p>&gt; The ONLY way to document a program is to understand that almost everything you
write needs to be an answer to the question, &quot;What problem existed that led to
this piece of code being created?&quot;  Your job is <i>not</i> 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&#x27;ve decided to work with them].<p>What do you think of akkartik&#x27;s take on the imperative to effectively communicate whole-program concerns at the global level? &lt;<a href="http:&#x2F;&#x2F;akkartik.name&#x2F;about" rel="nofollow">http:&#x2F;&#x2F;akkartik.name&#x2F;about</a>&gt;