Or why you should give meaningful names to example variables
I bent over my desk in frustration, suppressing the urge to scream so as not to upset the rhythmic clack-clack of my coworkers. I’d been frustrated all morning by a particularly nasty React infinite re-rendering issue that I just couldn’t get working. The urge to scream came when, my own toolbox exhausted, I turned to Google.
You see, it looked like someone else had come across the same issue and had decided to record a solution for prosperity (and internet points). I eagerly scanned the page for the sample code that would save my morning. Finding it, my eyes were drawn to the dreaded fooBarBaz and I knew my morning was about to get a whole lot worse before it got better.
I actually love the history of programming and the little easter eggs fellow developers have passed down (my personal favourite - I am a teapot). These help to make this job interfacing with computers much more fun and human. I can appreciate that the practice of using fooBarBaz in naming example functions and variables has a long and storied tradition dating back at least to the Tech Model Railroad Club at MIT circa 1960. I acknowledge that the use of fooBarBaz is primarily not to introduce any distractions from the point which is being demonstrated. I also think that we should pretty much stop using them.
I am always awed by the amount of information my fellow developers have left out there for me on the internet. So many people in this field seem to have an innate need to help others, leading them to put in countless hours to fill Stack Overflow and blogs with useful information. I can only imagine that the people putting in their time and effort to this end are hoping that their efforts will help as many people as possible. fooBarBaz gets in the way of that.
Let me take off my developer hat for a second and put on my recently discarded, slightly misshapen and battered psychologist one. Interweaving complex facts into stories is a time tested technique which facilitates learning. Here in Australia, the technique has been used for tens of thousands of years by the Aboriginal and Torres Strait Islander peoples to help them to remember important and complex information such as the locations of waterholes across vast tracts of inhospitable desert. Our brains are networks of interconnected neurons so we are more likely to hold on to what we have learned when we are able to integrate new information into our current knowledge base. The modern term for this is associative learning.
Additionally, as I’m sure you’ll remember from school, keeping learning interesting has been demonstrated to be a powerful motivator which energises learning.
When we take all this time and effort to communicate with our fellow developers we can and should harness the advantage of associative learning and intrinsic motivation to make sure that the information we are putting out there is as useful as possible to as many people as possible. To this end I believe that we should give as much thought to meaningful naming when creating example code as we do in our own codebases.
Marijn piggybacks off our existing knowledge about Springfield’s favourite cartoon characters to give extra meaning and interest to this example. We know that Itchy and Scratchy are a mouse and cat respectively and so most definitely not the same.
Consider the same example but rendered with the dreaded Foo/Bar instead:
To seasoned developers, this might be easy enough to parse: you’ve read hundreds of examples like this and so have learned the association between Foo and Bar and internalised it. But this creates a barrier for learning for new developers who have not yet internalised this rule and instead increases the mental load for them to understand the concept. It also misses out on creating that little spark of interest or joy to help pique the reader's interest and so increase their motivation to understand the underlying concept.
I am not saying there is absolutely no place for fooBarBaz (although I think their utility is limited). The best way to use these terms is to emphasise that anything could be put in a certain place. An example of this is when we’re talking about arguments and parameters in JS functions. You see, there is no type checking in vanilla JS and so if we have a function like the following that takes a parameter and simply logs its value to the console, it doesn’t matter what type of argument we pass in:
I believe that these terms have the most utility in this case as their purpose is to emphasise that their type doesn’t matter. I would also add the caveat to this that using these terms in this way is only suitable when you are producing content for experienced developers who are going to have built a working understanding of these terms.
Even if this is aimed at experienced developers, I still believe that more meaningful names would be better in this example:
Another example where more meaningful variable names would be useful is in relation to metasyntactic variables. These variables are commonly found in source code and are intended to be modified or substituted before real-world usage. Whilst these variables are only placeholders, I believe that it is also better to use a variable name which offers more context to your developer comrade to assist them when they are reading and implementing the code in future.
We work in a wonderful profession with a rich history, where many people are willing to donate their time to helping to educate and mentor their fellow programmers. Using meaningful variable names in place of fooBarBaz is one way that we can ensure that this effort is worthwhile and helps as many people as possible. It lowers the barriers to entry for the profession, helping to create a more diverse and welcoming programming community.
So ditch the fooBarBaz (but not the Teapot) and go forth and spark joy!