Hacker News Reader

Comment by ggm | Hacker News Reader

I have always felt a literate program is probably for many of us, a future deliverable on the hack we've implemented up front.

Very very few people can start from the abstraction and get TO a literate outcome without a lot of false steps along the way.

Or, as an alternative, the LOC of a literate program has to include the 100x cost of exploring how to carve it out of the block of mud we start from, including making our own tools.

View on HN

The cool thing is that if it's valuable, you can leave the iteration artifacts in the literate document, not as commented-out blocks like we often see, but as a part of the explanation of how we arrived at the final version of our solution. Not all code that's in the document has to end up in the compiled/executed files.

As appendix, maybe. A program which rehearsed the mistakes before arriving at the conclusion could be a good read, in linear order but probably not what you expect. I tend to think this is more like a rolls-royce, you want to be able to look in the boot at the old water pump but only to clarify how closely it resembles the current one, if the current one breaks: if the current water pump works, thats what you want to see first if you open the bonnet.

"Reader, she married him" as the first words of the book, not the last basically.

I had an instance of this where I built up a rather contrived data structure over time and ended up putting what is basically a blog post into the repo to explain the history of that data structure: https://github.com/majewsky/rust-jmdict/blob/main/CONTRIBUTI...

>Very very few people can start from the abstraction and get TO a literate outcome without a lot of false steps along the way.

But don't writers face the same issue with their text? Am I the only one who writes more code than what ends up in a PR? Isn't that exactly what the Git history is for?

Sure. So how many published works do we ever see the git logs for? Significant literary works, one or two per author, pre digital era. Galley proofs, or Marcel Prousts chaotic revisions which G Scott Moncrieff fought with doing his translation, and then Terence Gilmartin. Dickens, some of them. Most writing? Never seen.

Reply on news.ycombinator.com