Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

6
  • 6
    Literate programming, as well as comments in general, is not about what your code is doing. You can read that from the code itself. It is all about why and how, and this essential information is almost always missing without a proper literate programming. Needless to mention that the "why?" part quite often would involve elaborate and complicated mathematics, sometimes plots and tables, sometimes diagrams. Literate programming tools are necessary to maintain such comments in a readable way. Commented Feb 28, 2012 at 7:59
  • 1
    @SK-logic fair, but the point that David Thornley is making is that even the WHY can turn out to be a misleading lie (one that is actually even harder to comprehend). Commented Oct 11, 2012 at 16:57
  • 1
    +1 Knuth was writing back in the (thematic) wild west days of programming when working in an "advanced" language meant writing "C" almost on top of the metal instead using machine code. Memory was so tight variables and other names were usually just single letters, often reused from scope to scope. The vast majority of programs where turn-key one shots written and maintained by one person each with his own eccentric style. Having to take over a code base was more decrypting than reading. There was no source control etc to help out. Commented Jun 30, 2016 at 2:13
  • 1
    Knuth was looking down the road, 30 years ago today. He knew programs would get bigger, more complicated, be written by teams with shifting members, would run for years or decades and require input, assessment and eventually acceptance from non-programmers. Literate programming was an idea for addressing all that. He was roughing out what we today call business logic and BDD. The core idea being that programmers would know what to do and non-programmers could follow along. As noted, the idea failed because no mechanism exist to enforce the linkage between the "literate" text and the code. Commented Jun 30, 2016 at 2:18
  • BTW: This is why I like "self-documenting" languages like Objective-C. At first the code looks way to cluttered with absurdly long method names, but even a programmer who doesn't know the language or the API can quickly puzzle out what the code is doing. Best of all, change the code and the "comments" change in sync automatically. Of course, that's why Objective-C was written with autocomplete built in. Without it, writing Objective-C is pretty hellish. Commented Jun 30, 2016 at 2:23