How long should a name be?

[SJT]

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:

• Avoid setting and reading a variable on the same line if you have no further use for it. Instead see if you can avoid it with a tacit (or ‘point-free’) expression. For example 1 reverse\ rather than (a;)reverse a:. Perhaps you can use a lambda to limit the scope of the variable: {(x;reverse x)}. Worst case, have one ‘throw away’ name that you use only for ephemeral values, set and consumed almost immediately. (I use niq for n’importe quoi, but whatever.)
• Set a variable once only: within a function have a name mean just one thing. The obvious exception is a series of amendments: updates to a table; amends to a list; building up an HTML document.
• The distance in your code between setting and reading a variable is how long your reader has to remember the association. Keep those distances short.
• Use a name that recalls but does not rehearse the value associated with it. For example, imq rather than incomingMessageQueue.
• Some variables form natural groups. For example, you might partition a message into a header and a body. Give them names of the same length.
  

  head:msg@...
  body:msg@...

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