In this post, Premier Consultant Mannie Tagarira shares his thoughts on naming conventions in software development.

Naming is difficult.

Whether deciding to name a child, a business, or a brand, you’ve undoubtedly faced the dilemma of picking something witty and relevant, or something classic that’ll stand the test of time. Thankfully, this task needs doing only once or twice… well, for most people, anyway. Naming is especially problematic for software professionals because there seems to be no escape. I’ve been developing software for some time now; at times I feel like that’s all I get paid to do: name things. That, and deciphering error messages (build, runtime, or otherwise).

How it begins.

Shortly after writing our first line of code, we’re tasked with providing an identifier for a transient in-memory data store— we’ll call it myvar. We quickly progress and realize that copy-pasta is a (dangerous yet prevalent) thing, so we write your first structure for code reuse and we call it doTask(). Our proof-of-concept script grows. We now have several related methods that perform a variety of actions, several variables that make no sense without additional context, and the feeling of annoyance as we realize how poorly we designed the scripts.

There must be a better way!

Object Oriented Design swoops in to save the day. We happily refactor our 10,000 line script into smaller, more focused classes. Organization becomes our new addiction; we adopt a new folder structure that separates the models from the code that uses these data structures. Exciting… until we realize the problem we’ve just created for ourselves: we need to adopt a consistent naming convention for all variables, methods, classes, packages, and so on. “It’s okay”, you think to yourself, “I won’t have to name another things after this!”

This’ll be our last naming party… right?

Look at how clean and well organized everything looks! A pat on the back is well deserved. Wearing a smug grin (our work is second to none, after all), we hit Build. The horror… the frustration… the sadness… not to mention the embarrassment… every emotion we’ve learnt to identify since childhood sets in— you broke the build. Also, what do you mean you didn’t back the script up before the big refactor. “Let’s call it a day…” Rage quit!

Tomorrow is a new day.

Software development has often been referred to as the process of converting caffeine into code (more aptly solutions) so after our morning coffee we (ahem, teamwork) formulate a plan to get the day started:

• Create a local Git repository.
• Dump the existing project code into said repo.
• Create a remote Git repo (hmm, we need a name for this, don’t we?).
• Push our code upstream.

Several missing semi-colons and an Advil (Paracetamol and Ibuprofen are also good options) later, our app comes back to life. Quick… Commit. Tag (ugh, we need a name). Don’t even think about breathing funny! Push!

Some things are just out of our control…

Our prototype-turned-production-app now seems to have a life of its own: people are giving it complements, other apps are trying to find ways to integrate it into their Circle of Cool (apps that form an ecosystem are cool, but maybe that’s just me). All the while, its insecurities –zero documentation, one unit test, and plenty of technical debt– are mounting quickly as the fans ask for more. This thing is growing faster than we can manage. We need a way to keep track of outstanding work, current work items, release schedules, and automate releases & notifications; you know, a fan club… but first we need a name!

…but not everything is!

Naming is one of many things that fall under the Best Practices umbrella of software development, along with automation, testing, and monitoring.  While selecting the right name might seem mundane and of little consequence, picking the wrong name will lead to, at the very least, discreditation even if playful amongst your peers. If you’re unsure about your naming choice, refer to the universal code quality metric: number of expletives uttered in reference to your code per minute. I believe this metric also applies to names since they contribute to the overall quality of something, even if it’s only perceived; perception is reality in most situations: imagine your surgeon introducing themselves as Dr. Henry Jekyll… eek!

The right name, a good name, will:

• be clear and intuitive, not allowing for follow-up questions for clarification;
• be descriptive yet concise, removing the need for follow-up questions for clarification;
• not make your peers want to buy you a dictionary for Secret Santa, along with long list of follow-up questions for clarification!

TL;DR

Productivity and efficiency (pronounced developer happiness) are hinged on reducing one’s cognitive overhead; if I have to stop what I’m doing to process why something is the way it is, there’s a chance that the design was flawed. Norman Doors exist everywhere; let’s get rid of them one name at a time.

If you find yourself asking yourself the following questions, there’s a chance someone else will:

• What do the variables numberOfCats, numberOfDogs, and numberOfPets hold? I would like to think, based on the current context, numberOfPets = numberOfCats + numberOfDogs.
• Is the WeeklySubscription class related to Subscription, MonthlySubscription, and YearlySubscription classes? It would make sense that WeeklySubscription, MonthlySubscription, and YearlySubscription exist as subclasses of Subscription.
• Why is the messaging service called Raven? “Okay… this one is actually pretty witty. You just have to know the pop-culture reference… oh wait, you don’t watch Gam…? Never mind then.”

It’s okay to pick a boring unexciting name. It’ll save you a lot of explanation in due time!

Now, if I may be excused… I need to go and find a name for this article…