Of Well commented code and Literate code
Well commented code
I have written more than a couple of dozen technical articles- most of them guided towards newbies, ’cause:
- I love scratching the surface of a million things, and
- 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
Programming and writing about it. 