The Why of Code

There’s been some discussion lately about literate programming and related ideas (syntactic sugar, et. al.) centered around a quote from Abelson & Sussman’s book, Structure and Interpretation of Computer Programs: “Programs must be written for people to read, and only incidentally for machines to execute.”

Nutrun thinks literate programming potentially masks inefficiencies and bugs. By way of example, he says, “The moment something like submit_the_payment_and_send_a_message_to_the_customer…somehow doesn’t send messages to the customer, while making a couple of redundant roundtrips to the database, we’re in trouble.” But that is true whether or not the code is literate.

I think it’s a disingenuous example. The issues here are error-handling and orthogonality rather than whether the method name is or isn’t literate. Literate programming doesn’t prohibit bad programming practices. It’s meant to convey a quick understanding of the code’s purpose. If customers were complaining they weren’t getting their messages, a literate method name clues me in faster than one named, say, “execute.”

It’s obvious that code must be written for both people and machines. The difference is that machines execute code while people interpret it. We need to understand why the code was written. Code doesn’t have to be perfect English but it has to be more than merely readable; it also has to be unambiguous. Literate programming aims to accomplish that goal.