3 ms·

I'm always sad when I find such lists and there's no consideration of Literate Programming as developed by Donald Knuth to create TeX and METAFONT. Before comi

I'm always sad when I find such lists and there's no consideration of Literate Programming as developed by Donald Knuth to create TeX and METAFONT. Before coming across it, I always had a problem when projects transitioned to being in multiple files, or past a number of lines of code which made maintaining a mental model and reviewing the code difficult/time-consuming. With LP, I can quickly look through a PDF, using hyper-linked ToC or index, and control/command click at a point and then have the editor open at that point. I've been trying to keep a list of notable texts on it, and of Literate Programs published as books: https://www.goodreads.com/review/list/21394355-william-adams?ref=nav_mybooks&shelf=literateprograms https://www.goodreads.com/review/list/21394355-william-adams...

camel-cdr 2y ago
The list is missing "Retargetable C Compiler, A: Design and Implementation", which is one of my favorite programming books. It's a literate program of a full c compiler.
- WillAdams 2y ago
  Thanks! Much appreciated! Will be sure to add that.
Chris_Newton 2y ago
I used literate programming for a multi-year project in a specialist field with a lot of technical details once. I was working solo but on behalf of a client, and I was working in Haskell to replace an earlier system I’d written in Python, so I wanted to leave documentation with clear explanations of how everything fit together for anyone who might have to maintain that system later. The pros and cons of the literate style turned out to be refreshingly obvious. It felt more like writing a book than a program. That provided a clear narrative structure and led to thorough documentation, which really was very useful when revisiting areas that had been designed and implemented months or years earlier. On the other hand, it also required a clear vision, a coherent view of how the whole story could eventually fit together, to know where to put things. For a project like that, IMHO it was a trade-off worth making, in the same sense that maintaining any good documentation (or a test suite, or build automation, or…) is an investment of time up-front that pays dividends later. I would be more cautious about adopting literate style for a larger project with a team of developers and a process where the system is developed in small increments with relatively little planning first. Editing literate code is also like editing a book: you aren’t merely changing the code, you’re also rewriting the story. You probably need a team who are committed to doing that well for the idea to work, though again this isn’t really any different to any of those other up-front investments.

camel-cdr 2y ago

The list is missing "Retargetable C Compiler, A: Design and Implementation", which is one of my favorite programming books. It's a literate program of a full c compiler.

WillAdams 2y ago
Thanks! Much appreciated! Will be sure to add that.

Chris_Newton 2y ago

I used literate programming for a multi-year project in a specialist field with a lot of technical details once. I was working solo but on behalf of a client, and I was working in Haskell to replace an earlier system I’d written in Python, so I wanted to leave documentation with clear explanations of how everything fit together for anyone who might have to maintain that system later. The pros and cons of the literate style turned out to be refreshingly obvious. It felt more like writing a book than a program. That provided a clear narrative structure and led to thorough documentation, which really was very useful when revisiting areas that had been designed and implemented months or years earlier. On the other hand, it also required a clear vision, a coherent view of how the whole story could eventually fit together, to know where to put things. For a project like that, IMHO it was a trade-off worth making, in the same sense that maintaining any good documentation (or a test suite, or build automation, or…) is an investment of time up-front that pays dividends later. I would be more cautious about adopting literate style for a larger project with a team of developers and a process where the system is developed in small increments with relatively little planning first. Editing literate code is also like editing a book: you aren’t merely changing the code, you’re also rewriting the story. You probably need a team who are committed to doing that well for the idea to work, though again this isn’t really any different to any of those other up-front investments.