3 ms·

I wrote a moderate-size project (about 10K LOC) in literate programming with a self-made tool. I also read a couple books written in this manner, such as "C int

I wrote a moderate-size project (about 10K LOC) in literate programming with a self-made tool. I also read a couple books written in this manner, such as "C interfaces and implementations" by D. Hanson. I would not say it is a good way. The true thing is that code cannot be self-documented, thus documentation is necessary. But literate documentation is not the right way to do it. First, it is too crafty. The good documentation should be formal and have a definite standard structure that is repeated across all similar projects. It also should have an encyclopedia-like form of short standalone pieces interlinked into a bigger whole so you can start anywhere instead of reading it from start to end. Second, it is too programmatic. It has real code. But real code is not good to describe what is important. Try porting METAFONT to something else. METAFONT code is fully documented. In Pascal. And you want to draw it with JavaScript. It would be way more helpful to describe these algorithms without tying them to Pascal or any other specific notation. And then, once they are described in this form, add a document that maps them to a Pascal implementation.

rixed 1y ago
Similarly, I have written several smaller programs using my own literal programming tool, and although the experience is interesting as it forces you to think deeper at every step, I came to the same conclusion that the end result feels hard to return to, and that literate programming is no replacement for higher level languages.
- Propelloni 1y ago
  My first contact with literate programming was through Haskell, which has built-in support for it. It was great for learning a new language and a new domain. I abandoned the practice for day to day work, but occasionally return to it if I have to unlock a new domain. To me, it is a lot like rubber-ducking.
bluGill 1y ago
My problem with literate programming is it too often describes things that are obvious to someone who understands the code, while not describing the important things that are not obvious in the code. It is easy to write "++i; // increment i" which gives me no clue as to why i is incremented - if instead you just name the algorithm you are implementing I would understand. Document things that are not obvious "++i; // must be incremented in the middle here because some weird interaction where...". Document what the interface is. There are other good things to document, but literate programming is telling me what I already know - beginners have no business looking at real world code until they are not beginners (which can be as little as a few days if you are otherwise experienced, or a few years if just starting programming school). That comment about beginners is a nod to the sibling comment explaining how it is useful for a beginner. I've never found it useful myself, but I can see the value.
- fxn 1y ago
  That is not the hallmark of literate programming, but the hallmark bad/unhelpful code comments or docs. Like, you can also have bad/unhelpful function names or unclean and tangled implementations. "TeX: The Program" is a joy to read.
  - bluGill 1y ago
    Except that literate programming encourages that style by mixing comments with the code.
    - nothrabannosir 1y ago
      It doesn’t. Literate programming is letting the documentation, rather than the implementation, dictate the order and organization of the program. You could theoretically write a literate program that is nothing but code, if the code is so readable that it doesn’t need explaining. The distinction is that it is “human first” over “computer first”.
- fn-mote 1y ago
  > literate programming is telling me what I already know Referring to specific literate programs would make this comment easier to believe. Even my very first literate programs avoided this trait, so I really cannot relate. It sounds like you are describing trivial in-line comments instead of chunks of programs interspersed with explanations.
- f1shy 1y ago
  What you are describing as good is what literate programming is about, and what you say is bad, is exactly what literate programming tries to a avoid.
WillAdams 1y ago
The thing is, Literate Programming is not documentation --- if it was, _TeX: The Program_ and _The TeXbook_ would be interchangeable, and they are not (that plain.tex is not a literate program is a different discussion). When I write Literate Programs, it's mostly for future me so that I can remember why a particular approach was taken, or what the significance of the two slightly differently named variable is and why they are not interchangeable. If it's for others to use, then user documentation is a specific section of the program code, and possibly a totally separate document (only written after the fact when the UI and so forth is stable enough that things won't change). FWIW, I am working to reimplement parts of METAFONT in my current project (need the curves, and want an implementation which will also allow me to write out a .mp file) and I'm finding _METAFONT: The Program_ very helpful.
- thiagoharry 1y ago
  > FWIW, I am working to reimplement parts of METAFONT in my current project (need the curves, and want an implementation which will also allow me to write out a .mp file) and I'm finding _METAFONT: The Program_ very helpful. I have a reimplementation of parts of METAFONT as a hobby project. In fact, it is no longer METAFONT; it is a language based on METAFONT. However, I used the same Hobby's algorithm to generate curves. It understands pens, paths and renders it to an OpenGL texture. The results are not compatible with Knuth's METAFONT, as I use floating-point numbers instead of the fixed-point arithmetic. It is still under development and needs some cleaning, but if what you are developing is for personal use or is free software compatible with GNU Affero GPL, perhaps parts of the code, or even the whole, could be of use. https://github.com/thiagoharry/weaver-interface-metafont https://github.com/thiagoharry/weaver-interface-metafont

rixed 1y ago

Similarly, I have written several smaller programs using my own literal programming tool, and although the experience is interesting as it forces you to think deeper at every step, I came to the same conclusion that the end result feels hard to return to, and that literate programming is no replacement for higher level languages.

Propelloni 1y ago
My first contact with literate programming was through Haskell, which has built-in support for it. It was great for learning a new language and a new domain. I abandoned the practice for day to day work, but occasionally return to it if I have to unlock a new domain. To me, it is a lot like rubber-ducking.

bluGill 1y ago

My problem with literate programming is it too often describes things that are obvious to someone who understands the code, while not describing the important things that are not obvious in the code. It is easy to write "++i; // increment i" which gives me no clue as to why i is incremented - if instead you just name the algorithm you are implementing I would understand. Document things that are not obvious "++i; // must be incremented in the middle here because some weird interaction where...". Document what the interface is. There are other good things to document, but literate programming is telling me what I already know - beginners have no business looking at real world code until they are not beginners (which can be as little as a few days if you are otherwise experienced, or a few years if just starting programming school). That comment about beginners is a nod to the sibling comment explaining how it is useful for a beginner. I've never found it useful myself, but I can see the value.

fxn 1y ago
That is not the hallmark of literate programming, but the hallmark bad/unhelpful code comments or docs. Like, you can also have bad/unhelpful function names or unclean and tangled implementations. "TeX: The Program" is a joy to read.
- bluGill 1y ago
  Except that literate programming encourages that style by mixing comments with the code.
  - nothrabannosir 1y ago
    It doesn’t. Literate programming is letting the documentation, rather than the implementation, dictate the order and organization of the program. You could theoretically write a literate program that is nothing but code, if the code is so readable that it doesn’t need explaining. The distinction is that it is “human first” over “computer first”.
fn-mote 1y ago
> literate programming is telling me what I already know Referring to specific literate programs would make this comment easier to believe. Even my very first literate programs avoided this trait, so I really cannot relate. It sounds like you are describing trivial in-line comments instead of chunks of programs interspersed with explanations.
f1shy 1y ago
What you are describing as good is what literate programming is about, and what you say is bad, is exactly what literate programming tries to a avoid.

WillAdams 1y ago

The thing is, Literate Programming is not documentation --- if it was, _TeX: The Program_ and _The TeXbook_ would be interchangeable, and they are not (that plain.tex is not a literate program is a different discussion). When I write Literate Programs, it's mostly for future me so that I can remember why a particular approach was taken, or what the significance of the two slightly differently named variable is and why they are not interchangeable. If it's for others to use, then user documentation is a specific section of the program code, and possibly a totally separate document (only written after the fact when the UI and so forth is stable enough that things won't change). FWIW, I am working to reimplement parts of METAFONT in my current project (need the curves, and want an implementation which will also allow me to write out a .mp file) and I'm finding _METAFONT: The Program_ very helpful.

thiagoharry 1y ago
> FWIW, I am working to reimplement parts of METAFONT in my current project (need the curves, and want an implementation which will also allow me to write out a .mp file) and I'm finding _METAFONT: The Program_ very helpful. I have a reimplementation of parts of METAFONT as a hobby project. In fact, it is no longer METAFONT; it is a language based on METAFONT. However, I used the same Hobby's algorithm to generate curves. It understands pens, paths and renders it to an OpenGL texture. The results are not compatible with Knuth's METAFONT, as I use floating-point numbers instead of the fixed-point arithmetic. It is still under development and needs some cleaning, but if what you are developing is for personal use or is free software compatible with GNU Affero GPL, perhaps parts of the code, or even the whole, could be of use. https://github.com/thiagoharry/weaver-interface-metafont https://github.com/thiagoharry/weaver-interface-metafont