Do programmers dream of electronic poems?

I was once called a massive wanker for proposing that programming is a branch of literature¹. I won't deny the pretentious tone of the claim, but I do think there are connections between both disciplines and that they are worth exploring.

Programming is realized in the written word; it's more or less accepted these days that code addresses other humans as much as the computer, that (with the exception of Perl) it's read much more frequently than it is written. It takes a short leap to go from that to acknowledging that, rather than instructing a computer what to do, the job of the programmer is explaining to human beings what we want a computer to do².

If we accept this, then it's not enough to just worry about "readability" —choosing good names for variables, avoiding excessively dense or nested code—: we must direct our efforts towards communicating an idea as effectively as possible.

It's usual for authors to say that they don't have readers in mind while they are working, that they write for themselves, maybe to prove that they won't make concessions to the public or to the market. But in reality everybody writes to be read, even if the ideal readers aren't concrete, even if they weren't born yet; if only subconsciously, writing entails the construction of a model reader, that is, an imaginary reader that guides the choices of the author, for example that of the level of detail that the text will require to be comprehensible³.

To professional programmers, a model reader should approximate not only their current colleagues but the future versions of themselves, any potential future owner of the code, even someone that may need to browse it occasionally looking for information. How are we supposed to put ourselves in the shoes of such a range of abstract people? There probably isn't a satisfactory method; the best I can think of is to picture ourselves approaching the code with the context we had one, two, five years ago. No matter how hard we try, our code won't be accessible to every possible person; our job is rather to make a conscious, unfrivolous decision of who is going to be left out.

The fiction writer has the unlikely task of balancing an infinitely complex sytem, making decisions about each element and the whole: the order in which information is revealed and plot unfolds; the length, the cadence of the phrases; how dialogue and descriptions are interleaved; even the associations that the choice of an adjective is expected to evoke in the mind of the reader. Much in the same way, programmers have a wide set of tools that can aid or hinder the task of expressing the purposes of their program: the directory and file structure, the module interfaces, the length of the functions and the order in which they are laid out, the use of comments, the decision to name expressions and the names that are given to them, the style in which data is manipulated and program flow is controlled, even the placement of whithespace between lines.

As we are writing code and especially during the correction stage (when the problem is solved in our heads, the program already works and we can rearrange it in the way that best communicates the solution) we should make an effort to look at it with the eyes of our model reader. What will they see as they list the project directory or browse its repository, when they read the documentation and follow the links we provide, when they open a file and read its header and the first few functions that we pull their attention to? How well are we conveying our idea to someone that follows that path?

Professional writers sometimes work with an editor; someone that can give impressions, exchange ideas with the author, suggest (or demand) changes⁴. The editor works as a concrete reader that complements the model reader from the creative phase; I think this role resembles that of the colleague that peer reviews the code during development⁵.

Some authors suggest to put distance with the text after writing the first draft, letting it rest in a drawer for weeks or months⁶. This allows them to come back to it with fresh eyes, as if someone else had written it, and detect problems that the proximity of day-to-day work had hid from them.

Programmers can't afford to forget about the code for a while; in most cases we will want to put it to work as soon as possible if not before. There's a lot of improvement potential in going into production, much more than what the mere distance with the code could provide. But that doesn't necessarily invalidate the drawer method: in a sense, putting the code in production is like leaving it in the drawer.

If we subscribe to the idea of Refactoring, our code is never really done, it's always possible (and reasonable) to take a program that works and polish it, improve its structure. After the initial development of a piece of code, after testing it and debugging it, once we consider that the functionality is acceptable, we can forget about it for a while; we can come back to it, months later, review it with the benefit of the distance, look for improvement opportunities, refactor.

In the pursuit of annoying a wider group of people, I could conclude by saying that some common programming methods could be equally applied to prose writing: Divide and conquer, Keep it simple, stupid, Don't repeat yourself… I certainly write as if I was programming, which explains the tendency of my pieces to look like loosely coupled sequences of paragraphs; sequences that dilute towards the end and finish abruptly, like this one.

This was originally published in spanish.