💾 Archived View for gemini.circumlunar.space › ~ew › 2021 › 20210115-de-literate.gmi captured on 2022-04-29 at 11:54:05. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
Today I was reminded about "Literate Programming":
https://irreal.org/blog/?p=9413
via
I remember that I was really fascinated, when I heard about it the first time. I made some half hearted attempt with \LaTeX, weave, and tangle. I failed fast and forgot about the whole thing for quite some time.
Years later I added org-mode to my emacs configuration and came across this again. I made a more serious attempt to use org-babel and literate programming to produce source code needed for a training class, with some success.
Shortly after that I tried this with a small software project of mine and failed again. I found that this style of programming did not work well with my /explorative/ programming. By that I mean that I had no clear understanding, of how to achieve my goal. There were way too many fast moving parts in order to find out, what works and what doesn't. So I abandonded the master text file at some point and worked with the derived code files instead.
Only recently I had a chat about literate programming with B, a very bright software/hardware (asic design) person. To my surprise he largely agreed with my observation. His bottom line: Literate programming is possibly the best way to thoroughly document a piece of software, when it has reached a mature state. The person who has to support this work with small changes here and there will highly appreciate a coherent view of why the code looks the way it does. However the tooling must still be there and must be working smoothly.
Two years ago I had made my '~/.emacs.d/init.el' configuration file /literate/. And now I de-literated it obeying the "Keep it simple!" credo. The literate representation did not add noticable value to my configuration. I moved a little text into the derived file as comments. I consider my configuration fairly small and definitely not guru style --- allthough the file weighs in at approximately 1000 lines featuring 44 'use-package' statements. However, it is not subjected to continous rework and tweaking.
Cheers,
~ew