News for hackers. Stuff that matters.
Re:Literate programming tool for any language by bluGill on Friday June 20, 2025 @09:02AM (#44327317)
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.

Re:Literate programming tool for any language by fxn on Friday June 20, 2025 @10:30AM (#44328063)
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.

Re:Literate programming tool for any language by bluGill on Friday June 20, 2025 @10:38AM (#44328145)
Except that literate programming encourages that style by mixing comments with the code.
Re:Literate programming tool for any language by nothrabannosir on Friday June 20, 2025 @04:29PM (#44331781)
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”.

Re:Literate programming tool for any language by fn-mote on Friday June 20, 2025 @11:17AM (#44328541)
> 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.

Re:Literate programming tool for any language by f1shy on Friday June 20, 2025 @01:34PM (#44329976)
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.