2021-01-15

Literate Programming?

tags: software keepitsimple

Today I was reminded about "Literate Programming":

https://irreal.org/blog/?p=9413

via

https://planet.emacslife.com/

Literate?

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.

Not so much ...

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

Home