Hacker News Reader

Comment by mbrock | Hacker News Reader

I’m all for hyperlinks but I also think there’s something crucially valuable about presenting some kind of ordered, intelligible, linear narrative structure. The idea of organizing a program as a sequence of chapters is to me the core of literate programming. I do it by simply ordering my files with numbers. You can start reading at file 1, or you can skip the first chapters and jump to a more substantial chapter where the key concepts are already established… Feel free to start reading at the very end; this is also a good strategy for prose, see Adler’s “How To Read a Book.” Actually I think Adler’s framework would be very interesting to apply to programs. Literature isn’t just novels, it’s also monographs and anthologies and textbooks.

View on HN

This seems like a totally unrealistic and impractical way of organizing a codebase. Living, useful codebases under active development need to be searchable and well tagged rather than laid out in "chapters" in my experience. In most scenarios it is also not a great use of time to try and read through a codebase line by line from A-Z.

It works for me, it’s the only way I like to write programs, so I don’t know how to respond to the notion that it’s totally impossible. It’s not perfect, it has its own difficulties just like any way of doing things.

To clarify, and I mentioned this already, having “chapters” doesn’t mean you need to read every line in order. If chapter 1 is “Basic Setup of the BCK387 Chip” then you might want to skip to chapter 5, “Drawing Lines to the Screen” if that’s what you’re interested in, knowing that you can return for the preliminary details if you want.

Within any single source file, I will assume that you take some care to arrange parts in some sensible order. Why is it such a ridiculous idea to do this for the files themselves?

Usually the order imposed on files is to group like things together (instance variables, public methods, private methods, something like this). That’s actually somewhat hostile to the notion of making something read well from start to finish.

> linear narrative structure

IMHO, this is one of the three fundamental mistakes of literate programming:

1. Not everyone is an author or a teacher like Knuth is. Writing is actually hard.

2. A program is obviously not a linear thing. It is a network of interactions. The only way you can make it linear is to tell the tale of what happens in a given set of circumstances.

3. Docs and comments are prone to bitrot. You absolutely want to minimize then.

Everything that anyone has ever written a book about is also a non-linear network of interactions. Consider a textbook in any field. Physics is not a linear thing. Economics is not a linear thing. Even the thing a novel describes is not linear: characters are not linear, the world is not linear. You can linearize a program randomly, alphabetically, chronologically, or more usefully by order of module dependency.

Yes. There is never one view of a program, but multiple architectural views.

Literate programming in the sense of documenting a program like a monograph is too one-dimensional.

I would like to see an emphasis on test inputs/outputs instead. Given all the Test vectors the actual code becomes irrelevant. It seems that we focus on the code because it used to be the bottleneck, plus it’s the densest piece of information in the system…and takes less paper to print.

In a world where modules must be constantly integrated, I’d rather read the test traces than the code itself.

Good programmers can simulate the code in their heads and internally generate the traces…but presumably the point of literate programming should be to remove that burden from the reader.

Reply on news.ycombinator.com