Monday, November 14, 2016

Literate Programming... A Revisit

For someone reason (nostalgia?) I've been re-visiting Donald Knuth's concept of Literate Programming.

(For a quick intro, critique and discussion on this approach see this blog entry and the responses.)

I first discovered Literate Programming via looking at TeX sources in the 1980s.  Then I became somewhat obsessed with the approach around 1992 with the publication of Literate Programming by Knuth. This is still one of my favorite books on programming.

I still like to thumb through TeX: The Program (likely the largest Literate Program ever written).

Perhaps I am starting to revisit Literate Programming because of my full-time-deep-dive into embedded programming (again).  Still stuck with C and code that is supposed to work (I deal more with "firmware" than software these days -- code that can't just be frequently updated, is hard to unit test and must be very, very reliable).

Literate Programming doesn't fit well in today's rapid development, big team, fastest-time-to-market culture.  But, when I am writing control systems with little instructional software/literature available (e.g. learning how to spin a BLDC motor using sinusoidal waves), I start thinking about approaching it in a literate style.

Shhh... don't tell my partners, but I am definitely thinking about using cweb  or perhaps cwebx for this ;)


Charley Shattuck said...

Very interesting Todd! I've been thinking about how to go about writing Forth firmware for my steno keyboards that would be easy for C programmers (everyone else who might want to work on the code) to read and understand. I already had one guy read through the current version, ask some questions, and translate it into C for the Arduino IDE. I just can't see myself learning to do it in C in the first place. (I'm myforth Charley in case it's not obvious).

Todd Coram said...

Hi Charley,
C still remains (in my eyes) not a very good language for playing with hardware. All of my (BLDC) motor spinning work is/was in Forth and there is no way I would have been able to learn as much as I have about sinusoidal (and other forms of) commutation via the compile/link/download/run cycle that is inherent in embedded C IDEs.

I am running into similar code sharing issues as you (where, in my case, my partners are not fluent in Forth). So, I may be far enough past the experimental stages in order to justify rewriting the code in C. I've been programming C almost as long as Forth (since the early 1980's!), so it is an easy transition for me, but I feel your pain.

Interestingly, there have been literate programming attempts in Forth, but they tend to miss out on one critical element: Knuth's system was not only very well thought out, but has been used for years to produce a fairly large body of work (mostly by Knuth). Most of the other literate programming systems are not as "fully baked" and people tend to base their dismissal of the technique on these systems.

Anyway, I miss the days of shadow screens. I think that worked quite well as a documentation system for Forth (if you can stand to be as spartan, concise and minimalist as Chuck Moore ;)

Personally, I think developers would learn a lot by sticking with your excellent myforth system, but I say that as a fan :)