How long should a variable or function name be?
A well-established tradition encourages us to use clear, meaningful names; names that explain what the variable contains, what the function does.
Here is an alternative strategy – don’t.
Bertrand RussellA century ago, Bertrand Russell thought words denote whatever they denote by being some kind of compressed description. (His colleagues in linguistic philosophy soon devised better theories of reference.) Early programming languages commonly limited token names to e.g. eight characters. At its launch in 1981, Smalltalk abandoned the restriction with glee, hoping people might be able to use the language without formal training. It was some kind of a thrill then to see names such as ProcessMessage
and incomingMessageQueue
. (The tradition endures in Java; perhaps not the thrill.) In these we have descriptions without even the compression.
The Iverson College meetings often included a few guests curious about the APL family of languages. At Oxford in 2014 Arthur Whitney demonstrated his nascent operating system kOS and the text editor he had written for it: four lines of k. A guest asked him if the code would not be clearer with longer, explanatory variable names. Whitney thought briefly, then replied, “No”. Blogging later, our guest wrote how someone else had afterwards helped her see long variable names tend to obscure the transformations between them, which are more interesting.
But I have a different quarrel with explanatory names – the explanation. Reading English engages a part of my brain quite distinct from what I use for math. It’s the story-telling part; it responds to poetry and explanations. The word incomingMessageQueue
paws at my mind, demanding attention like a needy pet. I see people queuing. I think about messages. I think about about people who send me messages, and about how messages travel. English is a wonderful medium for essays and poetry. But there is a reason mathematicians devise notations – to abstract irrelevant detail away. In math we say (over and over again) x rather than the number you first thought of. For thinking mathematically, we need something bare, something without distracting associations.
So not English words. (Or whatever language you think in.)
Smalltalk’s desire for code that any English speaker could read was understandable – but treacherous. English words suggest transformations or relationships that might mislead. For example, when I flip a coin it reverses a random number of times and lands heads or tails with equal probability. When I flip
a matrix it transposes exactly once. As the guest on a recent Array Cast episode said, when you use an English-like reserved word you might need to reflect on whether you are getting what you think you are getting; but a symbol such as ⍉
(the APL symbol for q’s flip
) leaves no uncertainty.
So how long should a q name be?
A strong hint comes from the default argument names. X has always marked the spot, stood for the unknown, so x
is a function’s first argument; and y
and z
follow along. Single-letter names are fine – for short functions anyway, perhaps up to three lines long.
Keep in mind: naming a value is a request to your reader to remember the association. If you create a local variable, you ask your reader to remember the name/value association for the rest of the function. Be gentle:
For me the sweet spot for names is 2-4 letters. My incoming message queue can be imq
or msgs
, with the expanded version in the comments.
imq: ... / incoming message queue
pim:{[msg] / process incoming message
..
}
pim each imq
That’s my sweet spot. What works for you?
Further reading: Three Principles of Coding Clarity