The Literacy of Programs
September 30th, 2007 | by Bill Kayser |
What is the purpose of a computer program?
Your colleagues and you all write software. You generate software prose on a daily basis, crafting these artifacts called programs, line by line. You utilize a common language that you all agree upon, a language which bears scant resemblance to a spoken language. So what is it that you are creating? What is the purpose of these lines of code?
You might say a program elaborates how a computer is to execute an algorithm. It describes what the system should do and how to do it. As programmers, we are the narrators and the computer is our audience. That’s basically what we were taught in our very first computer class.
Donald Knuth, Professor of the Art of Computer Programming at Stanford University, challenged this idea over twenty years ago when he first proposed the idea of “literate programming.” Knuth felt that computer programs were first and foremost works of literature, to be read and appreciated by humans more than computers. A programmer should take the same sort of care and attention in writing a program that an essayist takes in writing prose. He devised a special language called “WEB” which was basically a programming language that resulted in two artifacts: one compiled into the machine language of the computer and the other compiled into a document for humans. A program listing in WEB not only read like an article, it actually looked like one because it was based partly on Tex, the typesetting language Knuth developed in the 70’s for publishing technical papers.
This would have been a much more challenging idea in the days before open source and tools that readily made source available and searchable, like Archie and the World Wide Web. It wasn’t as easy to find examples of source code and even book authors were reluctant to disclose real applications in all the gory detail. Most publications relied heavily on pseudo-code when trying to present samples for human consumption. Before object oriented programming and the subsequent wave of class libraries and frameworks, programs had to do much more. Real programs were just too ugly and verbose to put on display.
Open source has heralded in a new era of visibility for software artifacts. The authors of Linux and Apache know that it’s not enough for their APIs to work as expected. It’s not just how the systems behave that falls under scrutiny, but the actual source code itself. The source of the Java Class Libraries makes itself known to most java programmers on a daily basis when they click on a stack frame in the debugger. Successful open source contributors are very self conscious about how the source code looks. The computer may not judge their triply nested loops but other programmers certainly will. Their audience is first and foremost other software professionals.
So our program is a work of literature, then what is its purpose? The purpose of our program is not to describe for the computer what we want it to do, but to describe for the programmer what the computer will do. If that sounds subtle, then think about this the next time you are editing code in your IDE. Is your "audience" really the computer? Or is it the person in the office next to you?
Most conscientious programmers like to think of their code as maintainable–well documented and readable–but even the best of us may be tempted by obscure or clever shortcuts when we think nobody is looking. Focus your work on a human audience. If you’ve ever done pair programming, you know that having someone looking over your shoulder makes you take a bit more care with what you type in. So imagine that someone is always looking over your shoulder, or that every line is going to be subjected to a team code review, scrutinized by your peers. Write the code not for yourself, not for the computer, but for them. Take pride in how your program communicates its cleverness, not just in being clever. Choose names that not only mean something but could actually be read out loud in something that sounds like English. Comments shouldn’t be an afterthought–your disconnected scribbled notes in the sidebar. They should be interweaved in the source, flowing with it and filling in the prose to help the reader move effortlessly through the narration of what the computer is doing. And remember: the best writers are avid readers.
Those are just a few examples of how programs should play to an audience of humans and not a computer. I’ll be covering more in upcoming installments of this column.
By Vaibhav on Sep 30, 2007
Hello Bill,
While I can’t help but agree that code should be written so that it can be ‘read’; one problem that I often come across (and not just in Nagarro, but in a lot of open source code that I get to read) is that there are often times useless comments.
These comments actually break the flow of a piece of code you are trying to read. And the main reason for these comments is that programmers are pummeled again and again by people telling them that comments are critical.
Like you very rightly said, a program is a piece of literature; does one need to be a good writer to judge correctly which comments are needed and which are simply in the way? Or is this something that can be taught/learned?
Cheers.
By Vaibhav on Oct 1, 2007
Hmm… just noticed by Ajay, the picture has the IIT Delhi Convocation hall in the background… Interesting… what’s the story behind that?
By Bill Kayser on Oct 2, 2007
Hi Vaibhav. Yes, that’s me during my visit to Delhi a couple of years ago. Manas Fuloria gave me the full tour including the campus of IIT, which I’d heard so much about.
I agree with your point about useless comments. Yesterday I came across a class called “LinkAdapter” which stated plainly in it’s class comment “The methods for the LinkAdapter class.” It’s hard to imagine a less helpful class comment, and this was from a very competent developer! I think people are sometimes conflicted between leaving useless comments and leaving nothing at all.
My opinion is that when thinking about what should be commented a developer should think about their “audience”. Imagine what someone would be looking for if they ever happened upon this class, method or variable. Use your experience as a programmer looking at other people’s code to determine what information you would want to know. Don’t focus on guidelines and the compulsion to leave comments. In the spirit of literate programming, focus on the people who will be reading them.
I talk more about this in the next post.
By Amit Jain on Dec 16, 2007
Vaibhav,
Most of the time the useless comments are produced when code commenting is done after the coding is complete. A developer does this just to satify himself that he is following good coding practices.
It is a good practice to write comments at the same time (or earlier than) you write your code.
Commenting while you code forces you to make sure your logic “sounds right”. Plus, your comments are going to be more accurate when the understanding of what’s going on behind-the-scenes is fresh in your mind.