Hacker News Reader

Comment by plafl | Hacker News Reader

I think the main problem with LP is philosophical: it is used so you can deeply understand the whole program but most people want to understand a part and ignore the rest. So for example extracting how Tex renders math equations is almost impossible without understanding the whole (some people kindly did this and published a paper using SML). This actually is related to your comment because it's impossible to "navigate" or to "debug" the code, or at least I'm unaware of how could it be done in a simple way (that is, with existing tooling) and so if you want to learn how Tex is written you must proceed page by page of "TeX: The Program" instead of randomly jumping through code, hacking here and there. It's like learning mathematics axiom by axiom. I personally find it unproductive as learning for me is highly non sequential. If knowledge is a graph of concepts I want to explore as I wish, not following another's predefined serialization.

View on HN

I've found literate programming helps in one main situation: where I am writing and want to force myself to very thoroughly think through a difficult and self-contained section of code that has to be understood as a whole. In that case, the narrative format makes me much less likely to overlook edge cases, and I find it easier to go back in and make changes later on. I wouldn't ever write a larger system in that way, but on that scale it's like working with a metronome in music: it's a form of discipline that produces almost magical results.

I agree with this: I found it very hard, at least until I got a good sense of the overall structure and conventions etc, to be able to understand just one part and ignore the rest.

On the other hand, ironically, Knuth recommended getting familiar with the program by picking up one particular part and "navigating" the program to study just that part. (See https://youtu.be/D1jhVMx5lLo?t=4103 at 1:08:25, transcribed a bit at https://shreevatsa.net/tex/program/videos/s04/) He seems to find using the index (at the back of the book, and on each two-page spread in the book) to be a really convenient way of "navigate" the program (and indeed randomly jumping through code, as you said), and he thinks that one of the convenient things about the "web" format is that you can explore it the way you want. This is really strange (to us) as the affordances we're used to from IDEs / code browsers etc are really not there, but it makes a bit of sense when you consider that books are Knuth's life, and he must find things like flipping pages with a bookmark in the index page at the back of the book etc really second-nature.

(BTW if you know someone who has the super-obscure interest in making WEB programs actually navigable with hyperlinks etc, do consider https://github.com/shreevatsa/webWEB/discussions or if you know some better way of finding such people let me know :P)

Very much agree.

I think that splitting your software into well-documented modules and APIs is a superior approach to lp. Whereas not much software is well-documented these days, where "well-documented" means for me:

a) high-level narrative of the why and how of the code, including descriptions and (informal) correctness proofs of the important algorithms in the code (can be just a doi to a paper)

b) detailed documentation of parameters and return results of the functions that comprise the module(s)

Reply on news.ycombinator.com