Of Well commented code and Literate code

by Amit

Well commented code

I have written more than a couple of dozen technical articles- most of them guided towards newbies, ’cause:

  1. I love scratching the surface of a million things, and
  2. I want to write them down- the reason which I attribute to a combination of {willing to share, increasing the tally of my articles, a quick buck, boast}, with one or two overpowering the other most times

Since, I write them for newbies, I want them to be very detailed, with all the fancy screenshots, et. al. (The first tine we met face-2-face, Sriram Narayanan actually appreciated that). A direct fallout, or shall I say a good fallout, because of that is I really feel inclined to do the same when I write the code comments whenever I write a piece of code I want someone else to understand.  For eg. this code

Literate Programming

This programing paradigm was conceptualized by Donald Knuth to introduce a new programming style where you would write code the way you think, not the way your particular language makes you to. You define separate chunks of code in your program, as you cook it up in your mind and then you weave them together to form a large program which is closer to the way you think, than you are made to think. Top-down, or Bottom-up just doesn’t cut it at times. You have to define this, before that, declare that before this and what you get is code which is a lot different from what you would have liked to.

Consider this piece of Scheme code written using/for plt-scheme. It is written using the scribble/lp (since plt-scheme 4.1.5) plt-scheme module which provides support for Literate Programming in Scheme. Here we  have defined a chunk of code and named it as squarefunction. Next, you could define N more chunks of code, in the way your mind cooks it over and then combine the chunks together. For eg, the source code of  chat-noir.

Well commented code v$ Literate code

Now, as you can see from my naive example, which is the first time I have made any attempt to write literate code, I started thinking that well commented code serves my purpose just fine. Hence, I really didn’t get that intuitive motivation for writing a Literate Program. But there is a difference- I write well commented code for others to  understand my code, I would write Literate Code for myself, ’cause that is the way it is being manufactured by the cells in my brain, and my programming system shouldn’t hinder that flow.

Related post: http://www.wisdomandwonder.com/link/2100/literate-programming-in-scheme and my Stack Overflow question looking for the intuitive motivation

Literate Programming tools and systems

See the Wikipedia entry