Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Literate programming is much more than just commenting code

justinmeiners.github.io

Post reply on HN
Print view View original

11–20 of 112 posts

Re: Literate programming is much more than just commenting code

#11

Post by BeetleB »

The problems one will run into with literate programming:

1. Lack of tooling.

2. Refactoring becomes nontrivial

3. How one would write a program in literate style will vary widely from person to person. If you write your code in literate style, it may be easy for you to follow it years later and modify it, but it likely will not be the case for a coworker. If they have to modify the code, the cognitive load will not be too different from that of just dealing with well written code.

Disclaimer: I've written two nontrivial programs literate style that I continue to rely on and occasionally modify years after writing them. It works as advertised.

Re: Literate programming is much more than just commenting code

#12

Post by rektide »

Building a Habitable Computing Environment[1] was a recent blush i had with a "literate" computing project, this time less about programming specifically & about system setup/config.

I confess I'd rather forgotten what literate specifically meant beyond code comments describing the flow, but i did find it to be a remarkably comprehensive & understandable document, a prime example of how we might teach & understand computing. Even if it did leave me puzzling out what a number of the many many many scripts were for!

Certainly the overall project of computing needs a lot of help, ways to explain itself. Ive seen tons and tons and tons of "dotfiles" projects, but none have gotten anywhere near to as comprehensible as this literate programming project, from what I've seen.

[1] https://tess.oconnor.cx/config/hobercfg.html https://news.ycombinator.com/item?id=30748033 (19 points, 1d ago, 0 comments)

Re: Literate programming is much more than just commenting code

#13

Post by Yaina »

k__ wrote: post #10
Yaina wrote: post #8

Earlier quoted context omitted.

I mean rust supports markdown comments and can compile them into documentation.[1] That's pretty good in my book in terms of documentation. [1] https://doc.rust-lang.org/rust-by-example/meta/doc.html

I wouldn't call it good. But better than nothing, I guess.

I think it's as good as it gets. The rough principal is there: You have one file, and you can derive the documentation and the program from it with different compilers.

The idea of reading code like a book seems extremely flawed to me, and any attempts to create such languages either look like regular source code with slightly different syntax or are barely comprehensible (e.g. TeX)

Re: Literate programming is much more than just commenting code

#14

Post by goosedragons »

k__ wrote: post #6
dwohnitmok wrote: post #5

Are there any large (> 5 people teams) projects written with literate programming? Also are there any IDE plugins or error stack trace/debuggers for literate programming? I haven't really paid attention to literate programming in a long long time and I'm curious if the field has advanced. (Also I don't understand this: "A typical literate file produces many source files." Why? Why would you care about having multiple…

"Also are there any IDE plugins or error stack trace/debuggers for literate programming?" Good question! I always think it would be nice to just write Markdown sprinkled with code, but without IDE/editor support, it's dead in the water :(

R-studio supports this for R although you can sprinkle in other languages although they are 2nd class citizens unsurprisingly. Emacs has org-mode with babel that combined with poly-mode gets you every feature you'd expect in the major mode of the language you're writing in. Emacs also supports R-markdown/Sweave quite well.

Re: Literate programming is much more than just commenting code

#15

Post by goosedragons »

dwohnitmok wrote: post #5

Are there any large (> 5 people teams) projects written with literate programming? Also are there any IDE plugins or error stack trace/debuggers for literate programming? I haven't really paid attention to literate programming in a long long time and I'm curious if the field has advanced. (Also I don't understand this: "A typical literate file produces many source files." Why? Why would you care about having multiple…

You might still want multiple tangled files to follow a familiar app structure, or for languages that need to be compiled or if you don't want users to have to add the extra step of tangling the source before they build your program.

Re: Literate programming is much more than just commenting code

#16

Post by [deleted] »

Yaina wrote: post #13
k__ wrote: post #10

Earlier quoted context omitted.

I wouldn't call it good. But better than nothing, I guess.

I think it's as good as it gets. The rough principal is there: You have one file, and you can derive the documentation and the program from it with different compilers. The idea of reading code like a book seems extremely flawed to me, and any attempts to create such languages either look like regular source code with slightly different syntax or are barely comprehensible (e.g. TeX)

[deleted]

Re: Literate programming is much more than just commenting code

#17

Post by Koshkin »

QuikAccount wrote: post #7

I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed.

Self-documenting code is fine - until someone starts wondering why code does what it does, or if someone wants to generate documentation. (No, the lazy style, "OpenFile - opens a file", does not cut it.)

Re: Literate programming is much more than just commenting code

#18

Post by QuikAccount »

Koshkin wrote: post #17
QuikAccount wrote: post #7

I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed.

Self-documenting code is fine - until someone starts wondering why code does what it does, or if someone wants to generate documentation. (No, the lazy style, "OpenFile - opens a file", does not cut it.)

Python resolves this with docstrings but in general, assuming it is not self explanatory while a function exist, is it really necessary to go the whole nine with literate programming instead of just adding a few comments to explain why this exist. Self-documenting code with explanations when necessary is how most codebases already are. At least most good ones.

Re: Literate programming is much more than just commenting code

#19

Post by falcolas »

My favorite literate program still has to be the book "Physically Based Rendering". An optimized, feature rich ray tracer in the form of a textbook.

That said, I wouldn't personally want to try and collaborate on such a program with more than one other person. It would make for a great single-contributer OSS library though. Rubber duck debugging built right into the prose.

Re: Literate programming is much more than just commenting code

#20

Post by db48x »

Yaina wrote: post #13
k__ wrote: post #10

Earlier quoted context omitted.

I wouldn't call it good. But better than nothing, I guess.

I think it's as good as it gets. The rough principal is there: You have one file, and you can derive the documentation and the program from it with different compilers. The idea of reading code like a book seems extremely flawed to me, and any attempts to create such languages either look like regular source code with slightly different syntax or are barely comprehensible (e.g. TeX)

Have you actually read TeX: The Book? It is far from “extremely flawed”.
Post reply on HN