We spend most of our working hours on computers. Increasingly, many of us are now spending hours talking to computers as well. (No, I do not mean large language models!) Computer code, as a tool of data analysis, visualization, and sundry automation, is pervading ever more our fields of work.
Non-coders may surmise that equivalent programs should read equally well. After all, the primary audience of code is the computer, meticulous and impassive. Yet, if we see coding as analogous to writing, a different intuition emerges—writings that describe the same ideas can certainly read better or worse. Being well-written is a merit as valid for coding as for writing. Conversely, some writing foibles prompt me to think, “A computer will not be able to understand this!” It occurred to me that coding principles and best practices can actually help to promote more lucid writing. To underscore the parallel between writing and code, I present a selection of these principles below, borrowing some paragraph headings from the Zen of Python and parenthetical headings from chapter titles in R.P. Clark’s Writing Tools.
In the face of ambiguity, refuse the temptation to guess. Unclear references frequently raise my “computer-can’t-understand-this” warning. If a reference separates from its target, it can be ambiguous. Just what is ambiguous—the reference or its target, that is, the thing referred to? A thinking human can usually infer the answer from context, but we should write with compassion for the distracted reader, too. Moreover, some sentence structures create ambiguities that are truly confusing. When a reference is unclear, rework the sentence such that any reader can easily track the reference!
Avoid synonyms. What kind of programmer assigns two names to one variable? A confused one, I imagine. In code, consistent naming is often optional but improves code readability. For example, programmers usually use the same name for related variables in independent functions, even though doing so makes no difference to the computer, because this practice makes the code easier for people to read. In academic writing, specificity takes priority over lexical variety when we are referring to the same idea: Using a consistent word for each distinct concept helps our readers better follow our writing.
Define terms at first use. We should ideally tailor our writing to the readers, but we do not always know what they already know. When does a general, educated reader stop recognizing terms as they range from common to esoteric, such as from genes to DNA, RNA, CRISPR, or CRISPR gRNA? When in doubt, it is safer to explicitly define terms, especially those that are key to the discourse. Code fully embodies this principle: A computer cannot recognize any terms unless they are defined explicitly. New terms are defined either from existing ones (think, the reader’s background knowledge) or by reference to a citation. The same two strategies are available to the writer. Unlike in code, however, textual explanations are best given as new terms are introduced, not in advance, because our human brains do not have the reams of working memory to store every definition for later use.
Readability counts (pay attention to names). Programmers can give variables any name, but few would write “meow = cat + dog.” Similarly in writing, when introducing a new concept, choose a felicitous name to give the concept memorability and even a new layer of meaning. For example, how about the moniker WEIRD, as coined by cultural psychologists to denote a certain group of people?
Abstract frequent, long, irreducible phrases (climbing up and down the ladder of abstraction). Call such phrases key terms. (If they are not key, perhaps it’s time to rethink whether they need to be so frequent!) Academic writing teems with them. Key terms can be wordy jargon—for example, growth hormone-releasing hormone receptor—or refer to a specific group of interest—for example, people with deafness raised by parents with deafness. In both examples, all the content words are necessary for the meaning. Reciting such key terms each time may be unambiguous but can result in ponderous prose. Instead, abstracting these long phrases (maybe with a clever acronym!) can improve the narrative flow. Similar abstractions (“factoring”) are well respected in programming and ascribed high value (“modularity”). Abstractions in writing can also yield higher-level benefits. Crisper terms occupy less of our limited working memory, potentially revealing unnoticed larger patterns in our writing.
The analogy between English and programming languages can only go so far, but if we strive for writing that would be clear even to a computer, the writing will likely be clearer to human readers, too!
