24
Literate Programming is the process of writing documentation embedded with source code, rather than writing them separately as is more usual with software engineering. This provides a collection of benefits, but it requires reshaping how you think about the software development process.
When I'm writing a literate program, I start with the literate document. I write the basic boilerplate accepted by ReTangled. Then I structure the program logically with headings, describing how of each part of the program works in natural language. Finally, I write the code, following the descriptions I wrote in natural language. Sometimes those descriptions are minimal, little more than a typical API doc comment. Other times those descriptions are detailed explanations of the control flow of a process.
But once that is done, I now have two versions of the program: one in natural language and one in a computer language. Iteration from here has become more complicated. I have to modify the program in two places. On the one hand, it forces me to think twice about any new feature I want to implement and everything is now documented by default. On the other, it's a pain for fast iteration.
Most literate programs I've seen, including my own, have embraced fast iteration over full documentation. As far as I can tell, the new version of Entangled (a tool for Literate Programming) has eschewed it altogether.
It's possible this is a sign that literate programming isn't worth pursuing, at least not in the traditional Knuth-style. However, I still have hope for its future, because I believe in the value of documentation.
Most programs should be described in natural language before being written in a computer language. This allows using one mode of thinking while modifying the codebase before switching to another. It also enables considering design decisions at a high level before worrying about the details. This is often done through design documents and such, but those are often abandoned once the code is brought into existence.
So, going forward, my approach is going to be to prioritize iteration in natural language for my literate programs. I will consider what I want to change, write the description of it in natural language, and then implement it in code. That way everything is always fully documented, and I'm forced to fully think through design decisions before they're implemented.
I’m a bit confused here. I’ve used literate programming a lot, and used cweave and ctangle to create C and TeX sources from a single source file. Any iteration is done on the single original source, never on the intermediate C or TeX sources. Where does OP get into dissosiations between code source and document source?
I see this as the same problem where comments are not updated when code is and no longer match. I think he’s still talking about a single file here.
When you make changes to the comments or pseudo code to maintain the program, then you also need to do the same changes to the actual source code the compiler will use. As the human language comments need to be compiled to C by human, right? And this would end up thinking and maintaining the source code of two languages and hope they always align in their logic.
I never did this approach and only get this from reading the blog post.
The very idea of weave and tangle is that comment and code is (nearly) one. Just updating one makes no sense.
TeX and MetaFont are written in such a system, and you can read the TeX’ed source like a book.
The way I’ve used it is more that the text gives an explanation and a structure regardless of what the framework requires. It’s not the exact algorithm per se but it could if it’d ver very complex for some reason. It ends up reading like a book with code snippets in it which turns out to run the application.
I also generally edited the code directly and indirectly and then detangled or tangled such that the files were in sync.