Hacker Neue

Preferences
seanwilson parent
Maybe I'm missing something but how often is the English in literate programming repeating what's already written in the code? Does it work for large projects where it's often hard to explain all the parts in a linear way in the style of an essay?

I avoid code comments where I can because English is way less precise than code, it's an extra chore to keep the comments and code in sync, and when the comments and code inevitably get out of sync it's confusing which one is the source of truth. Does literate programming sidestep this somehow? Or have benefits that outweigh this?

juliangmp
I'm not sure who first coined this idea or put it in a book or where I've read it, but for code comments I generally like the "explain why, not what" philosophy. The "what" is answered by the code itself and should be easy enough to comprehend if your design is simple and your names meaningful. The "why" is much more important. Why does this parser check for some magic numbers at this specific offset and change some parameters if it finds them? If you don't explain that its because of e.g. compatibility with some legacy format, its gonna be a mystery to the reader.
kstrauser
This is dead on. Similarly, please document the "why not". As in, "here's some code that implements what should be an easy idea in an unexpected why. Why didn't I did it it normal way? Because this one special business case would break, and our customer got mad and threatened to cancel."
billfruit
I prefer to add huge amounts of comments, explaining in as much detail as I can, sometimes it will be a mini-essay in there. I write most of it before I write the code. It helps me formulate the code better. Later it serves as explanatory text.

Usually the problem with comments is that there is too less of it.

seanwilson OP
> Usually the problem with comments is that there is too less of it.

I've worked in a few code bases where many of the comments could be removed by using better function names, better variables names, and breaking complex conditionals into named subexpressions/variables.

And there was a fair chance comments were misleading or noise e.g. `/* send the record for team A */ teamB.send(...`, `/* if logged in and on home page */ if (!auth.user && router.name === 'home') ...`, `/* connect to database */ db.connect()`. I'd much rather comments were used as a last resort as they're imprecise, can be bandaids for code that's hard to read, and they easily get out of sync with the code because they're not executed/tested.

A block of comments to explain high-level details of complex/important code, or comments to explain the why or gotchas behind non-obvious code are useful though.

monkeyelite
The primary benefit of literate programming is being able to change the order of presentation.

But even then my experience doesn’t match yours. So you have some code. Who decided it would be that way? Do you have a picture of how it should look? Can you share a link to where you got this information? What problem led you do to this non-obvious thing?

taeric
I think this certainly happens a fair bit. Not at all uncommon to have a section that largely says what is going to happen next, which, fair that what is going to happen is what happens.

I think where it shines, is where it helps you break the code up, without having to break it up in a way that makes sense for the computer. Show an outline, but then drill into a section. The overall function can then be kept as a single unit, and you can sort of punt on sub sections. I tried this just recently in https://taeric.github.io/many_sums.html. I don't know that I succeeded, necessarily. Indeed, I think I probably should have broken things into more sections. That said, I did find that this helped me write the code more than I expected it to. (I also was very surprised at how effective the goto style of thinking was... Much to my chagrin.)

I will have to look again at some of the code I've read this way.

To directly answer the question of if it helped keep the documentation in sync, as it were, that is tough. I think it helps keep the code in a section directly related to the documentation for that section. All too often, the majority of code around something is not related to what you were wanting to do. Even the general use of common code constructs gets in the way of reading what you were doing. Literate programming seems the best way I have seen to give the narrative the ability to say "here is the outline necessary for a function" and then "this particular code is to do ..." Obviously, though, it is no panacea.

seanwilson OP
> I tried this just recently in https://taeric.github.io/many_sums.html.

Literate programming seems fine for heavily algorithmic stuff when there's a lot of explaining to do compared to the amount of code and the code is linear, but I was more thinking about how it works for common web apps where it's lots of mundane code that criss-crosses between files.

taeric
My gut is that this is where it should shine, oddly. The appeal of literate programming is that you can reflow the code to how you want to explain it. As such, if you had to add a bit of code in several places for a reason that you can explain in a narrative, then literate programming should help.

I say oddly, as I don't think I've seen it done for common web apps. I suspect that is largely because frameworks have not been a stable foundation to build on in a long time?

I can't help but think the old templates of old were a hint in how it would have worked fine? Have a section of the literate code that outlines the general template of a file, and where the old "your code goes here" comments used to denote where you add your logic, is instead another section that you can discuss on its own. (Anyone else remember those templates? Were common in app builders, if I recall correctly.)

WillAdams
My current project for a while was in a state where it was necessary to keep code in 3 separate files:

- gcodepreview.py (gcpy) --- the Python functions and variables

- pygcodepreview.scad (pyscad) --- the Python functions wrapped in OpenSCAD

- gcodepreview.scad (gcpscad) --- OpenSCAD modules and variables

as explained in: https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... and it worked quite well (far better than the tiled set of three text editor windows which I was using at first) and I find the ability to sequence the code for the separate files in a single master file very helpful.

teo_zero
> how often is the English in literate programming repeating what's already written in the code?

This had nothing to do with literate programming. I could as well ask "how often is the English in comments repeating what's already written in code? "

This item has no comments currently.