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

81–90 of 112 posts

Re: Literate programming is much more than just commenting code

#81

Post by lf-non »

I am not a big fan of the complex literate programming style involving code-generation which this article talks about.

But I recently discovered that Google's zx [1] scripting utility supports executing scripts in markdown documents and I combined it with httpie [2] and usql [3] for a bit of quick and dirty automation testing and api verification code and it worked out pretty well.

I imagine for most people nowadays jupyter or vscode notebooks are the closest it comes to practical literate programming.

[1] https://github.com/google/zx#markdown-scripts

[2] https://github.com/httpie/httpie

[3] https://github.com/xo/usql

Re: Literate programming is much more than just commenting code

#82

Post by User23 »

shakna wrote: post #66
throwaquestion5 wrote: post #36

Earlier quoted context omitted.

Problems 1 and 3 I could imagine. I would need to learn how to be a better writer to share a literate program. As someone experienced in the topic, What's the biggest hurdle when trying to refactor the code?

Refactoring becomes the dual problem space of both programming and editing. It's simply more work - but that "more work" is vitally important, tedious, and resistant to any kind of automated help.

With Emacs org-babel I just do the refactor using the normal tools for whatever language on the tangled files and then detangle it back to the literate document. There's no problem here.

Re: Literate programming is much more than just commenting code

#83

Post by davegauer »

medstrom wrote: post #75
kwhitefoot wrote: post #70

Earlier quoted context omitted.

> in a printed book, it is easier to find a previous page and compare a fragment on it with the current fragment. This is why I like plain text for everything (or Emacs Org Mode) because then I can have multiple frames showing different parts of the same buffer in Emacs.

You can also create several browser tabs visiting the same page. Of course, no one thinks to do that.

Make that several browser windows. And that's a good point. I sometimes end up inefficiently scrolling up and down a document to reference different parts of it. It almost never occurs to me to open another browser window with the same page for side-by-side reference.

Re: Literate programming is much more than just commenting code

#84

Post by antirez »

I think likewise. When I had to write the radix tree implementation for Redis I faced two problems:

- I needed a stable implemention as soon as possible, I had a performance issued that needed to be solved by range queries.

- The radix tree was full of corner cases.

So I resorted to literate programming, which is in general very near to my usual programming style. You can find it in the rax.c file inside the Redis source code, as you can see as the algorithm is enunciated, the corresponding code is inplenented.

Other than that I wrote a very extensive fuzzer for the implementation. Result: after the initial development I don't think it was never targeted by serious bugs, and now the implementation is very easy to modify if needed.

Re: Literate programming is much more than just commenting code

#85

Post by taeric »

t0suj4 wrote: post #68
taeric wrote: post #61

Earlier quoted context omitted.

The problem with self documenting code is that it doesn't help justify all of the parts into the whole. This is particularly troublesome in code where a refactor effectively isolated entire sections of the code, but the person that did the refactor didn't realize it, and now you have code that exists only for the sake of existing tests.

I interpret self documenting as writing the what in the code and writing comments about the why . While minimizing the places where you need to explain your code. My role of thumb is that if it's not obvious why that particular line is there and removing it would break functionality, add a comment.

I typically see "self documenting code" refer to code where function and variable names indicate the code without added comments.

Think:

    function square(x) ...
Versus

    function f(a) ...
Often includes all functions as named things, with little to no lambda usage, since names are seen as for the programmer, not for the computer.

Re: Literate programming is much more than just commenting code

#86

Post by taeric »

krageon wrote: post #74
taeric wrote: post #63

Earlier quoted context omitted.

You will be shocked to know that emacs and org-mode can do exactly this. You can tangle source, and go from the tangled source back to the section that generated that source. If you are wanting to just do cweb, then the debugging symbols already let you step through the source line by line without having to look at the tangled source.

> You will be shocked to know that emacs and org-mode can do exactly this. You can tangle source, and go from the tangled source back to the section that generated that source. If you actually use noweb and desire autocompletion or type reminders (or really anything an IDE does), then functionally it cannot. Literate programming (and noweb) is great for configs, but as set up it simply doesn't work right for real pro…

Orgmode can get you these things. Since the tangled source is full source, you will just have to index the tangled code and detangle after edits.

So, yes. The outline code will be less prone to this. But this is no different than the architecture document being ignored by the ide.

Re: Literate programming is much more than just commenting code

#87

Post by kkfx »

IMVHO literate programming is "describing an algorithm" like writing a book, witch is absolutely good, but demand much more time than directly writing code. That means: or we change actual "quick" development model to a new/old "slow" one, perhaps additive and coherent like classic systems (SmallTalk and LispM systems, the OS as a single application easy to change at runtime, anything available as a function/method anywhere) to keep the overall development speed useful enough or there is no room for literate programming.

Now, seen actual overall software quality (far less hacky than the past, but also unable to innovate, bloated, with gazillions of deps) we need to change back to days of the real innovation BUT that means we need to completely erase actual economical model centered on giants, witch can be "a little bit" difficult since they are giants and they do not like the idea to be thrown out of the window...

Re: Literate programming is much more than just commenting code

#90

Post by svat »

krick wrote: post #57

Ok, that will be unpopular. "Literate programming" is a non-invention by somebody (Knuth), who is very much revered by many programmers (many of whom never even actually read him), but who was — let's admit it — just terrible at writing readable code. I'm very much not a fan of the "Clean Code" by Martin, but he had a very nice example of refactoring some of Knuth's code to show you what I mean (although, it's kind o…

This is a surprising comment, and especially this part:

> it's kind of evident that writing clearly wasn't in Knuth's DNA just by reading his famous books

— my experience, from reading (parts of) several of Knuth's books and papers, is the very opposite: Knuth is one of the finest writers, and writing is clearly in Knuth's DNA — even among the many hats he has worn (mathematician, programmer, computer scientist, teacher), at heart of everything is writing. (His Selected Papers on Fun and Games includes some stuff he wrote in high school and college; even those show his spirit.)

IMO, every page of his is a delight to read. I think the issue for those who find it otherwise may be that he writes in a very personal way (his personality shines through), and for those who are looking for something bland or generic, this can be a surprise.

Then again, this may be one of the chief problems with literate programming in general (why it works so well with one author, and doesn't seem to have had much success with a large team): writing is very personal, and for many-person codebases something "generic" may in fact work better.

Post reply on HN