Literate Programming: Retrospect and Prospects
lambda-the-ultimate.org
lambda-the-ultimate.org
Many of the programmers repeatedly emphasized the importance of data structures to both understanding programs as well to solving the problem. And after noticing how I work, I find that to be true.
English documentation of the core data structures is more important than verbose description of the steps in the algorithm. This is the key thing that is different among progarms. By and large, we use the same algorithms again and again. And I can trivially find English documentation of those to understand rapidly. I don't need it in the code also.
And by documentation I mean something that explains at a programming language level with the identifiers etc. For git, it would be insufficient to say "trees are collections of blobs". I would need to know the struct names and an explanation of each of the members. And whether the "collection" is a array/list/hash etc.
Having looked into literate programming, it seems to emphasize documenting the algorithms more than it does the data structures. Hence it misses the "big picture" which is what is really needed.
I'm not convinced that LP is useful.
I don't go as far as Knuth and try to formulate a complete narrative of my program, but Leo's outlining features let me clone and regroup blocks of code on a task-by-task basis and document: "In these blocks, I'm implementing feature x," or "fixing bug y." It's very useful for getting the big picture and making sense of problems in the codebase. When using only a code editor, you waste a lot of time jumping through the project and searching through files, and I don't have that problem anymore.
That said, I've long wanted more expressive commentary in the trickier parts of the codebase. i.e. some kind of comment xml that IDEs make into a rich text area, for the diagrams and maths and whatnot.
Many programmers feel insecure abandoming their text editor -- because this is something they're accustomed to and which they understand conceptually. Some sort of nested structure expressed in a markup language like XML would be just as understandable conceptually. Many of the incompatibilities between languages would disappear if there was a widely used standard for such a code representation.
Instead, there are opportunities to enhance things in ways the are still perfectly useful in emacs/vi.
You can think of this as something like going from ext2 to ext3, then onto ZFS.
I do not believe this is the entire story, but it's an important part of it.
Incidentally I've used cweb before and can second their comments about it. It's a fantastic idea, that needs a bit of a refresh. Particularly getting away from simple commenting of how things are done to the why/data structure/higher level arena.