Depending on who you ask, you may hear that programming is a kind of logic or a branch of mathematics; that it’s akin to architecture or urban planning, or even painting or music. I don’t think any of those analogies is better than the next, or that there’s a single right characterization of the software creation process. Rather, I would say that programming, and more generally software design, can be approached in multiple ways. That, depending on their particular preferences, intellectual inclinations, and dispositions, different people will benefit from different mindsets when approaching their work.
To me, programming is a sort of writing. The more I read about literature and the more I think about and practice the craft of writing, the more I find new and interesting ways in which both disciplines can compare and inform one another.
Programming is realized in the written word. Today it’s common knowledge that code addresses people as much as computers, that it is read much more often than written. As Donald Knuth puts it: rather than instructing a computer what to do, the job of the programmer is explaining to human beings what we want a computer to do1.
If we agree with that, then it’s not enough to merely adjust the “readability” of our code —choosing variable names, avoiding excessively dense or nested code—: we must consciously direct our efforts towards communicating our ideas as effectively as possible.
∗ ∗ ∗
Authors often say that they aren’t thinking about their readers when they work, that they write for themselves, perhaps to stress that they won’t make concessions to the public or the market. But despite what they say, they still write for an audience, even if their readers aren’t concrete, even if they weren’t born yet. If only subconsciously, writing entails the construction of a model reader, an imagined reader that guides the choices of the author, such as the level of detail that the text will require to be comprehensible2.
Professional software writers should also model the readers of their code. Those readers should approximate not only current colleagues but the future versions of themselves, any potential future owner of the code, and even someone who may need to browse it occasionally looking for information. How are we supposed to put ourselves in the shoes of such a range of faceless people? There probably isn’t a satisfactory method. The best I can think of is:
No matter how hard we try, though, our code won’t be comprehensible to every possible person. Our duty is to make a conscious, unfrivolous decision of who is going to be left out by the choices we make.
∗ ∗ ∗
The fiction writer has the unlikely task of balancing an infinitely complex system, making decisions about each element and the whole: the order in which information is revealed and the 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. Similarly, programmers have a wide set of tools that can aid or interfere with 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 whitespace 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? What when they read the documentation and follow the links we provide, or when they open a file and read its header and the first few functions that we pull their attention to? How likely is our message to get through to someone walking that path?
∗ ∗ ∗
Some authors suggest putting distance with the text after writing the first draft, letting it rest in a drawer for weeks or months4. 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 the day-to-day work had prevented them from seeing.
Programmers can’t afford to forget about the code for a while; in most cases, they need to put it to work as soon as possible. There’s a lot of improvement potential in going into production, much more than what the mere distance with the code could offer. But that doesn’t necessarily invalidate the drawer method: in a sense, putting the code in production is like leaving it in the drawer.
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.
∗ ∗ ∗
At the risk of annoying an even wider group of people, I could conclude by saying that some common programming methods might as well apply to prose writing: Divide and conquer, Keep it simple, stupid, Don’t repeat yourself… I certainly write as if I were 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.
This was [[file:../../2021-02-01-suenan-los-programadores-con-poemas-electricos ][originally published in Spanish]].
Revised on September 2023.
Literate Programming, by Donald Knuth.
Lector in Codigo, by Álvaro Videla.
Writers sometimes work with an editor: someone who can give impressions and 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.
For example Chéjov and Stephen King.
0001-01-01