In Act II, Scene II of Shakespeare’s Romeo & Juliet, the star-crossed lovers challenge the crux of the Montague and Capulet feud by asking, “What is in a name?” I mean, after all, that which we call a rose, by any other name would smell just as sweet … Right?
Although I can’t speak to how things went down in Verona a couple of centuries ago, I do know that when it comes to programming, there is a lot that goes into a name.
Semantic satiation
Have you ever worked with a complex data structure or iterated over a deeply nested object when suddenly you reach a point where the variables that you declared no longer register with your brain and just sound like meaningless noise?
If so, you may have experienced semantic satiation: the psychological phenomenon when constant repetition or extended inspection/analysis causes a word or phrase to temporarily lose its meaning to the listener [1]. This article explores how strategically naming your variables can help you avoid these brain-draining occurrences.
In this article:
The cognitive importance of strategically naming variables
Best practice guidelines when naming variables
Metaphors change the way we think
The metaphors we choose when naming variables powerfully shape our perception of the stored data [2]. Let’s look at Roman numerals, for example. If I asked you to tell me what MMXXIII means, how would you respond? You could conduct a Google search or calculate the answer yourself:
What if I asked you what year it was, or showed the number 2023? My best guess is that you would have an easier time evaluating the latter examples rather than the former.
Examining our mental processes
Why was one framing of the question so much more difficult than the other? One compelling reason attributes the added difficulty to bad design [2], [3].
Think about it: Roman numerals are cumbersome, hard for our brains to use, and require additional mental energy to evaluate, as opposed to using Arabic numerals with the decimal system.
We are accustomed to saying the number eight and directly accessing its value 8, however, Roman numerals necessitate the expression VIII or “three more than 5.” Following this example, we can easily understand nine to be the value 9, but with Roman numerals, we understand this to be IX or “one less than 10 [2].”
Best practices from Clean Code [4]
When coding, the data we interact with is often an abstraction of whatever concept or object we are modeling. Our variable names can be thought of as an analogy that highlights shared similarities between the data they store [5].
Therefore, a good start towards effectively naming variables is to identify the intention or purpose of the data. In other words: why do we care about it, how do we describe it, what does it do, and how do we want to use it?
Consider the following examples when creating variable names that deeply align with our data.
Be explicit when naming your variables:
Given the example above, the constant variable d does not give us too much detail in terms of what it represents. If we were to reference this variable later in our program, it wouldn’t be readily apparent as to what type of attributes, methods, or behaviors this variable has. Even if we remembered that this was a date object, we would have no clue as to whether this represents someone’s birthday as opposed to the date of a doctor’s appointment.
Avoid confusion, disinformation, and misleading variable names:
Is this globally accessible variable really a list? Given this name, what type of unexpected behaviors may result from iterating over this string, posing as a list?
Make meaningful distinctions between variable names:
Identically named variables in the same scope are prohibited in JavaScript and are generally bad practice. Unfortunately, there is an allure—albeit very short-sighted—to create a quick workaround for this restriction by making non-informative distinctions between variable names:
Both variable names arguably reflect the content in the string of information they store, but we know very little about what distinguishes one rule variable from another. In other words, what can we infer about the distinctions between each rule, besides their numerical value? Perhaps it would be more descriptive to name them attendanceRule and participationRule?
I could go on ad nauseam about other common variable naming conventions, like avoiding hard-to-search variable names like i or hard-to-recognize characters such as O as opposed to zero, but these useful practices have been explained elsewhere in better detail and are outside the scope of this entry.
Slippery slopes
Instead, I want to emphasize the impact inaccurately named variables have on our thought processes. It is easy, if not natural, to try and reason through poorly constructed analogies when naming variables in our code, but superficial analogies and variable names that do not deeply reflect the data stored, render our code incomprehensible.
Given that we use names to reference almost everything when programming, from variables, functions, and arguments, to files, directories, and modules, it is important to comprehend and effectively structure the way you perceive them. This may seem rather basic, but it is also fundamental.
Final words
Long story short, we can’t relegate our best metaphors and analogies to literature and poetry—and if this article didn't convince you, take this hilarious skit from Abbott & Costello as a cautionary tale:
https://youtu.be/sYOUFGfK4bU?si=rkveeKtG1c50V4wQ
Oh yeah, and don’t let this be you…
References
[1] “Semantic Satiation.” Wikipedia. https://en.wikipedia.org/wiki/Semantic_satiation (July 27, 2023).
[2] K. Azad. “Math and Analogies.” Math Better Explained. https://betterexplained.com/articles/math-and-analogies (July 27, 2023).
[3] D. Norman, The Design of Everyday Things, Revised and Expanded Edition. New York, New York, USA. Basic Books, 2013.
[4] R.C. Martin, et al. Clean Code: A Handbook of Agile Software Craftsmanship. Upper Saddle River, New Jersey, USA. Prentice Hall, 2009. [Online]. Available: https://learning-oreilly-com. Accessed: July 27, 2023.
[5] P. Bartha. “Analogy and Analogical Reasoning”, The Stanford Encyclopedia of Philosophy (Summer 2022 Edition), E.N. Zalta (ed.). Metaphysics Research Lab, Stanford University. [Online]. Available: https://plato.stanford.edu/entries/reasoning-analogy. Accessed: July 27, 2023.