My Issues With Literate Programming
Fleetingmy issues with literate programming
I’m convinced that literate programming is THE way to go.
Yet, when trying it, there are stuff that I think make it difficult.
Most of them are simple questions that raise in my head and therefore consume cognitive load. So those are likely “good” difficulties, because they highly the fact that with literate programming, we gain a lot of freedom, and there is an complicated relation between freedom and comfort.
the program vs the tooling around the program
When I present my train of thought around the program, there are its line of code, but also the command that I run to make it work.
For instance, I might want to say that I use a venv, then say that I need the library x of y, like thit.
python3 -m venv myenv
source ./myenv/bin/activate
pip install x or y or z
It is not clear to me what should go in this document and what should be left outside of it.
Actually, often, the choice of x or y or z is as important as the code that imports it.
notebook style vs literate programming
Linked to the program vs the tooling around the program. Because if I put the tooling in the document, I am tempted to run the code directly from the document, without tangling it.
no LSP support
When editing the code in the document, it is out of context. Therefore, tools like LSP won’t work, unless I craft something to tangle the code, run LSP and then get the result back. We can think of mitigation, but it will still be not ideal.
We could also imagine a system of backlinks in the tangled document, even with automatic back propagated changes in the source documents but that would need back and forth in the document and the source code to ensure the document remains coherent while editing the code.
This is linked to the question of notebook style vs literate programming, because we would not have such issues if the document was directly executable, but that would still not be adapted to current tooling.
when does reproducible research start?
Linked to the program vs the tooling around the program. You might want to setup the earthly images and commands, but should I run them from the document or tangle them ?
how to organise the document?
The main argument about literate programming is the fact that you are not constrained by the structure of the program and can organise your document with whatever structure you deem useful to talk about the program.
Yet, nowadays, programs are split in several libraries. I am tempted to create one document per library, but would that mean being constrained? On the other hand, putting parts of libraries inside the document would mean losing the understanding of how the program ends up being structured, wouldn’t it?