4 ms·

I came to similar conclusions as the author about the usefulness of literate programming. Even after "taking it seriously" and "doing it right" and all those ot

I came to similar conclusions as the author about the usefulness of literate programming. Even after "taking it seriously" and "doing it right" and all those other no-true-scotsman type objections. (see HATEOAS/REST for more examples of these). Initially, I was super excited about the idea. Imagine a world where you take a book off the shelf and peruse a master programmer's in-depth explanation of the details of some famous software. What they were thinking, the abstractions they decided on, the algorithms they chose, the tradeoffs made. Wouldn't that be an amazing world to live in? In practice, very few pieces of software are written in a way that lends itself to a cohesive narrative. Software is written by numerous developers, layer by layer, often with hacks thrown in. New people come on, don't understand the whole thing, change parts of it, and move on. The requirements change, and the system contorts itself to serve multiple purposes that weren't envisioned by the original coders. Keeping normal auto-generated documentation up to date under those circumstances is already a herculean task, literate programming asks more: maintain a story and flow and an overarching rationale. It's just not possible for most software. There is a type of software that lends itself to literate programming: the kind of software Donald Knuth writes. Written by a single author, with encyclopedic knowledge of the problem domain, excellent writing style (Knuth is very funny if you've read his work), and above all, the programs Knuth writes tend to be "done" at some point. There are bugs to be fixed, but no new features are added that might drastically change the narrative. Most software isn't like that, but if yours is, then literate programming can be fun.

svat 8y ago
I agree that literate programming works well for Knuth because of the kind of programs he writes: mainly, as you say, that the program was written for a particular purpose, and when that's achieved it's "done". I wonder, though, whether it's necessarily true that more software cannot be like that. We could in principle move a little more in the direction of declaring programs done, and when new requirements come up, writing a new program to cover them. (Knuth has no qualms about having similar code in different programs; it's almost universally believed by other programmers today that that's a terrible thing.) The old program would continue to work well for its original purpose, and those who need the newer program would use that one instead. As with books: sometimes you need a new edition of a book, sometimes a reprint with corrections, and sometimes a new book entirely. It's ok if multiple books cover the same topics and even if they do so in slightly different ways; all that matters is that each is internally consistent — we don't demand that everything related to a certain domain and written by the same author(s) be in a single book. With programs, almost always they only grow and expand, with incremented version numbers.
- bitwize 8y ago
  > I agree that literate programming works well for Knuth because of the kind of programs he writes: mainly, as you say, that the program was written for a particular purpose, and when that's achieved it's "done". A piece of software in itself really isn't much of anything; the true value lies in the support you get from the development team. "Done" software is inherently unsupported, therefore close to worthless and probably won't be used in a production setting. > (Knuth has no qualms about having similar code in different programs; it's almost universally believed by other programmers today that that's a terrible thing.) It's a waste of programmer effort. In the open source realm at least, it would be a far more efficient use of programmer time and energy -- and easier on the users -- for programmers to collaborate on a single definitive program for each task, rather than reinvent wheels and confuse the marketplace with competing implementations of the same abstract process.
  - svat 8y ago
    Let's talk specifics. Here are four programs written by Knuth, in roughly chronological order: 1. The Algol-58 compiler he wrote for Burroughs (specifically, for their B205 machine). You can read about it in many places (http://ed-thelen.org/comp-hist/B5000-AlgolRWaychoff.html#7 http://ed-thelen.org/comp-hist/B5000-AlgolRWaychoff.html#7 , https://www.youtube.com/watch?v=QeiuVNDQg4k&list=PLVV0r6CmEsFzeNLngr1JqyQki3wdoGrCn&index=27 https://www.youtube.com/watch?v=QeiuVNDQg4k&list=PLVV0r6CmEs... , or in great detail at http://datatron.blogspot.com/2015/11/knuths-algol-58-compiler.html http://datatron.blogspot.com/2015/11/knuths-algol-58-compile...). This was written in the summer of 1960, debugged by Christmas, and put on their computers. The machine didn't sell very well in the US, but apparently it (and the compiler) was being used in Brazil over the next decade, successfully. I wouldn't call this "worthless" by any means; it did its job. (Of course one might argue that the prevailing model at the time was for software to get "done", so it wasn't really an exception.) 2. TeX. This is the most famous example. After developing it for about 10 years, he declared it done (https://www.tug.org/TUGboat/tb11-4/tb30knut.pdf https://www.tug.org/TUGboat/tb11-4/tb30knut.pdf) except of course for bugfixes. (He still looks at bug reports once every few years (https://cs.stanford.edu/~knuth/abcde.html#bugs https://cs.stanford.edu/~knuth/abcde.html#bugs), but there was exactly one bug reported during 2007–2013, and it was a really inconsequential one about the whitespace for how an "empty" macro would be printed in the error logs.) TeX is stable, well-understood (at one point of them there were hundreds of people who "knew" the entire program, which is unprecedented for a program of that size), and is very well-supported (see TUG, tex.stackexchange.com etc) — and in any case most of the questions these days are about LaTeX (a set of macros, with horrible error-handling, the opposite of TeX) or other packages, not about TeX (the program) itself. At Knuth's request, extensions are released as new programs (pdfTeX, XeTeX, LuaTeX) etc, and TeX stays the same (and even these programs have approached stability). This is definitely neither "inherently unsupported" nor "close to worthless" nor "probably won't be used in a production setting" — at any given point of time several publishers are using it in production, not to mention various others who are not even making physical books. 3. The Stanford GraphBase. This is a suite of programs, also published in book form (as literate programs). There are people still making use of these books, and these programs can be used as building blocks for other programs, e.g. for many of the ones that Knuth writes mainly for himself (see https://cs.stanford.edu/~knuth/programs.html https://cs.stanford.edu/~knuth/programs.html or https://github.com/shreevatsa/knuth-literate-programs/tree/master/programs https://github.com/shreevatsa/knuth-literate-programs/tree/m...). I don't think continuing to work on it, versus calling them done for now, would change anything about them. 4. Any of the programs on that page, e.g. say SETSET, which was written in February 2001, and “Enumerates nonisomorphic unplayable hands in the game of SET®”. Or the first two (SHAM, written December 1992, and OBDD, written May 1996) — both written mainly to find that there are “exactly 2,432,932 knight's tours [that] are unchanged by 180-degree rotation of the chessboard”. Once the job is done, just what is to be achieved by refusing to declare them “done”? (Incidentally, note that Knuth did figure out an improvement to SETSET, but wrote it as a new program. The original program is fine though.) In fact, if you look at the blog post by Joel Spolsky from 2002 on “Five Worlds”, in at least three of them (and maybe four), software can be quite commonly declared “done” (always, of course, except for bug fixes: “done” just means we've finally decided what the software is supposed to do; it's not the same as abandoning it even when it's not doing what we decided it's supposed to do). Throwaway code is often indeed thrown away, games get changes released as sequels or separate expansion packs, embedded software often cannot be updated anyway, and internal software can also often be "done". It's only the first one in which it is usually not.
pjscott 8y ago
You can sometimes find self-contained chunks of bigger software that lend themselves to that kind of style. For example, I once had to write a highly-compressed on-disk memory-mapped data structure for searching for large sets of phrases in text, along with associated payloads for each one. About half of that code is actual code; the other half is paragraph-length comments walking the reader through it. How are the payloads encoded? How does the index work? How do we handle prefix compression? What's the deal with unicode normalization? And so on. It was so much fun to write! These opportunities don't come along very often, but they do come along sometimes.
mikeliys 8y ago
The exact experience of mine. One of these types of software that lends to literate programming especially well is the one with lots of math behind it. The one with deceptively short functions which no matter how well expressed in no matter how clean programming language still look like magic. Seeing axioms, assumptions and approximations growing into theorems and formulas, budding lush crown of graphs, examples and intuitions, resulting in the end in sweet code fruits, all in the beautifully typeset form, is just... sweet. Oh! And good luck to all those who dump all the documentation and go straight to source code. Not this time, my friend. You can try but you will fail. She's just not one of those girls. When literate programming stops being some "hipster sh*t" and simply becomes necessity using it is even more so rewarding.

svat 8y ago

I agree that literate programming works well for Knuth because of the kind of programs he writes: mainly, as you say, that the program was written for a particular purpose, and when that's achieved it's "done". I wonder, though, whether it's necessarily true that more software cannot be like that. We could in principle move a little more in the direction of declaring programs done, and when new requirements come up, writing a new program to cover them. (Knuth has no qualms about having similar code in different programs; it's almost universally believed by other programmers today that that's a terrible thing.) The old program would continue to work well for its original purpose, and those who need the newer program would use that one instead. As with books: sometimes you need a new edition of a book, sometimes a reprint with corrections, and sometimes a new book entirely. It's ok if multiple books cover the same topics and even if they do so in slightly different ways; all that matters is that each is internally consistent — we don't demand that everything related to a certain domain and written by the same author(s) be in a single book. With programs, almost always they only grow and expand, with incremented version numbers.

bitwize 8y ago
> I agree that literate programming works well for Knuth because of the kind of programs he writes: mainly, as you say, that the program was written for a particular purpose, and when that's achieved it's "done". A piece of software in itself really isn't much of anything; the true value lies in the support you get from the development team. "Done" software is inherently unsupported, therefore close to worthless and probably won't be used in a production setting. > (Knuth has no qualms about having similar code in different programs; it's almost universally believed by other programmers today that that's a terrible thing.) It's a waste of programmer effort. In the open source realm at least, it would be a far more efficient use of programmer time and energy -- and easier on the users -- for programmers to collaborate on a single definitive program for each task, rather than reinvent wheels and confuse the marketplace with competing implementations of the same abstract process.
- svat 8y ago
  Let's talk specifics. Here are four programs written by Knuth, in roughly chronological order: 1. The Algol-58 compiler he wrote for Burroughs (specifically, for their B205 machine). You can read about it in many places (http://ed-thelen.org/comp-hist/B5000-AlgolRWaychoff.html#7 http://ed-thelen.org/comp-hist/B5000-AlgolRWaychoff.html#7 , https://www.youtube.com/watch?v=QeiuVNDQg4k&list=PLVV0r6CmEsFzeNLngr1JqyQki3wdoGrCn&index=27 https://www.youtube.com/watch?v=QeiuVNDQg4k&list=PLVV0r6CmEs... , or in great detail at http://datatron.blogspot.com/2015/11/knuths-algol-58-compiler.html http://datatron.blogspot.com/2015/11/knuths-algol-58-compile...). This was written in the summer of 1960, debugged by Christmas, and put on their computers. The machine didn't sell very well in the US, but apparently it (and the compiler) was being used in Brazil over the next decade, successfully. I wouldn't call this "worthless" by any means; it did its job. (Of course one might argue that the prevailing model at the time was for software to get "done", so it wasn't really an exception.) 2. TeX. This is the most famous example. After developing it for about 10 years, he declared it done (https://www.tug.org/TUGboat/tb11-4/tb30knut.pdf https://www.tug.org/TUGboat/tb11-4/tb30knut.pdf) except of course for bugfixes. (He still looks at bug reports once every few years (https://cs.stanford.edu/~knuth/abcde.html#bugs https://cs.stanford.edu/~knuth/abcde.html#bugs), but there was exactly one bug reported during 2007–2013, and it was a really inconsequential one about the whitespace for how an "empty" macro would be printed in the error logs.) TeX is stable, well-understood (at one point of them there were hundreds of people who "knew" the entire program, which is unprecedented for a program of that size), and is very well-supported (see TUG, tex.stackexchange.com etc) — and in any case most of the questions these days are about LaTeX (a set of macros, with horrible error-handling, the opposite of TeX) or other packages, not about TeX (the program) itself. At Knuth's request, extensions are released as new programs (pdfTeX, XeTeX, LuaTeX) etc, and TeX stays the same (and even these programs have approached stability). This is definitely neither "inherently unsupported" nor "close to worthless" nor "probably won't be used in a production setting" — at any given point of time several publishers are using it in production, not to mention various others who are not even making physical books. 3. The Stanford GraphBase. This is a suite of programs, also published in book form (as literate programs). There are people still making use of these books, and these programs can be used as building blocks for other programs, e.g. for many of the ones that Knuth writes mainly for himself (see https://cs.stanford.edu/~knuth/programs.html https://cs.stanford.edu/~knuth/programs.html or https://github.com/shreevatsa/knuth-literate-programs/tree/master/programs https://github.com/shreevatsa/knuth-literate-programs/tree/m...). I don't think continuing to work on it, versus calling them done for now, would change anything about them. 4. Any of the programs on that page, e.g. say SETSET, which was written in February 2001, and “Enumerates nonisomorphic unplayable hands in the game of SET®”. Or the first two (SHAM, written December 1992, and OBDD, written May 1996) — both written mainly to find that there are “exactly 2,432,932 knight's tours [that] are unchanged by 180-degree rotation of the chessboard”. Once the job is done, just what is to be achieved by refusing to declare them “done”? (Incidentally, note that Knuth did figure out an improvement to SETSET, but wrote it as a new program. The original program is fine though.) In fact, if you look at the blog post by Joel Spolsky from 2002 on “Five Worlds”, in at least three of them (and maybe four), software can be quite commonly declared “done” (always, of course, except for bug fixes: “done” just means we've finally decided what the software is supposed to do; it's not the same as abandoning it even when it's not doing what we decided it's supposed to do). Throwaway code is often indeed thrown away, games get changes released as sequels or separate expansion packs, embedded software often cannot be updated anyway, and internal software can also often be "done". It's only the first one in which it is usually not.

pjscott 8y ago

You can sometimes find self-contained chunks of bigger software that lend themselves to that kind of style. For example, I once had to write a highly-compressed on-disk memory-mapped data structure for searching for large sets of phrases in text, along with associated payloads for each one. About half of that code is actual code; the other half is paragraph-length comments walking the reader through it. How are the payloads encoded? How does the index work? How do we handle prefix compression? What's the deal with unicode normalization? And so on. It was so much fun to write! These opportunities don't come along very often, but they do come along sometimes.

mikeliys 8y ago

The exact experience of mine. One of these types of software that lends to literate programming especially well is the one with lots of math behind it. The one with deceptively short functions which no matter how well expressed in no matter how clean programming language still look like magic. Seeing axioms, assumptions and approximations growing into theorems and formulas, budding lush crown of graphs, examples and intuitions, resulting in the end in sweet code fruits, all in the beautifully typeset form, is just... sweet. Oh! And good luck to all those who dump all the documentation and go straight to source code. Not this time, my friend. You can try but you will fail. She's just not one of those girls. When literate programming stops being some "hipster sh*t" and simply becomes necessity using it is even more so rewarding.