The Literacy of Programs

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.

Share and Enjoy