3 ms·

Literate programming only works for small scripts and narrative documentation, not for e.g. API documentation.

WillAdams 2y ago
OIC. I guess that the books at: https://www.goodreads.com/review/list/21394355-william-adams?ref=nav_mybooks&shelf=literateprograms https://www.goodreads.com/review/list/21394355-william-adams... which include a typesetting system, a font design language, a 3D renderer, and an MP3 implementation qualify as "small scripts"? What is the threshold for such? TeX.web outputs some 20,619 lines of Pascal code for conversion to C and compiling.
- ReleaseCandidat 2y ago
  "Doesn't work" does not mean that you can't write such books/programs/documentation. It means nobody (yes, yes, exceptions ...) can maintain such code. Look at Jupyter Notebooks - the most used literate programming environment nowadays - and their usual content. The main problem of documentation isn't solved by literate programming: how can you make sure that any relevant documentation has been updated, so that the docs are still in sync with the code.
  - WillAdams 2y ago
    I find that having the documentation in the same file and interactive with, and having the ability to include formulae and diagrams helps immeasurably in ensuring that the documentation is updated as the code changes.
    - ReleaseCandidat 2y ago
      This sounds logical, yet I have never seen that in my own code, the code of colleagues at work or other code. If the documentation is not somehow automatically tested against changes in the code, the documentation in the same file is almost always worse (as in "more wrong") than adding the changes in another document. I don't know why it's easier to remember or for others to check for updates in "special" files.
nocman 2y ago
not true: "This book describes pbrt, a physically based rendering system based on the ray-tracing algorithm." ( https://www.pbr-book.org/3ed-2018/Introduction https://www.pbr-book.org/3ed-2018/Introduction ) and: "This book (including the chapter you’re reading now) is a long literate program." ( https://www.pbr-book.org/3ed-2018/Introduction/Literate_Programming# https://www.pbr-book.org/3ed-2018/Introduction/Literate_Prog... )
- ReleaseCandidat 2y ago
  And now imagine maintaining the code of PBR, and with more than 5 people working on it at the same time. Literate programming is great for reading, although I prefer having "real code" (which can normally be extracted, that's not a problem) to read too. Btw. there is a newer - 2023 - edition available now: https://www.pbr-book.org/4ed/contents https://www.pbr-book.org/4ed/contents
  - nocman 2y ago
    I'm not saying it is for everyone, or for every project. My point was that "Literate programming only works for small scripts and narrative documentation" is far too wide-sweeping of a statement. There are plenty of non-trivial examples of its use, and it obviously "works" for some people.
    - ReleaseCandidat 2y ago
      It certainly does, but these "some" really are exceptions. Just try it for yourself, edit PBR and compare the experience to "just" editing the source code of PBR (yes, of course, not being used to something doesn't help). To be honest, I haven't looked at PBR for more than a decade so maybe I would succeed nowadays, but I doubt that. I guess realising that literate programming is literally [sorry] writing a programming book should be enough of an argument to know that it isn't suitable for most people. And no, a white-paper is not a "programming book" suitable for most people to read ;)
- CyberDildonics 2y ago

OIC. I guess that the books at: https://www.goodreads.com/review/list/21394355-william-adams?ref=nav_mybooks&shelf=literateprograms https://www.goodreads.com/review/list/21394355-william-adams... which include a typesetting system, a font design language, a 3D renderer, and an MP3 implementation qualify as "small scripts"? What is the threshold for such? TeX.web outputs some 20,619 lines of Pascal code for conversion to C and compiling.

ReleaseCandidat 2y ago
"Doesn't work" does not mean that you can't write such books/programs/documentation. It means nobody (yes, yes, exceptions ...) can maintain such code. Look at Jupyter Notebooks - the most used literate programming environment nowadays - and their usual content. The main problem of documentation isn't solved by literate programming: how can you make sure that any relevant documentation has been updated, so that the docs are still in sync with the code.
- WillAdams 2y ago
  I find that having the documentation in the same file and interactive with, and having the ability to include formulae and diagrams helps immeasurably in ensuring that the documentation is updated as the code changes.
  - ReleaseCandidat 2y ago
    This sounds logical, yet I have never seen that in my own code, the code of colleagues at work or other code. If the documentation is not somehow automatically tested against changes in the code, the documentation in the same file is almost always worse (as in "more wrong") than adding the changes in another document. I don't know why it's easier to remember or for others to check for updates in "special" files.

nocman 2y ago

not true: "This book describes pbrt, a physically based rendering system based on the ray-tracing algorithm." ( https://www.pbr-book.org/3ed-2018/Introduction https://www.pbr-book.org/3ed-2018/Introduction ) and: "This book (including the chapter you’re reading now) is a long literate program." ( https://www.pbr-book.org/3ed-2018/Introduction/Literate_Programming# https://www.pbr-book.org/3ed-2018/Introduction/Literate_Prog... )

ReleaseCandidat 2y ago
And now imagine maintaining the code of PBR, and with more than 5 people working on it at the same time. Literate programming is great for reading, although I prefer having "real code" (which can normally be extracted, that's not a problem) to read too. Btw. there is a newer - 2023 - edition available now: https://www.pbr-book.org/4ed/contents https://www.pbr-book.org/4ed/contents
- nocman 2y ago
  I'm not saying it is for everyone, or for every project. My point was that "Literate programming only works for small scripts and narrative documentation" is far too wide-sweeping of a statement. There are plenty of non-trivial examples of its use, and it obviously "works" for some people.
  - ReleaseCandidat 2y ago
    It certainly does, but these "some" really are exceptions. Just try it for yourself, edit PBR and compare the experience to "just" editing the source code of PBR (yes, of course, not being used to something doesn't help). To be honest, I haven't looked at PBR for more than a decade so maybe I would succeed nowadays, but I doubt that. I guess realising that literate programming is literally [sorry] writing a programming book should be enough of an argument to know that it isn't suitable for most people. And no, a white-paper is not a "programming book" suitable for most people to read ;)
CyberDildonics 2y ago