What's in a Name

Many developers will have heard this quote attributed to Phil Karlton:

"There are only two hard things in Computer Science: cache invalidation and naming things."

Despite the tongue in check nature of this quote most engineers would agree with the sentiment that although the naming of variables, methods and classes would seem trivial it can actually be quite hard and often causes great head scratching.

But what are the root causes for this and why is it so important? Are developers just lacking creativity or is there more than meets the eye with this aspect of programming?

Communication Channel

The reason that deciding on a name can cause a developer anxiety is because he or she realises that this isn't just about what this thing should be called, more importantly its about how to adequately communicate its purpose.

What does this variable represent? What does the method do?

It will often be the case that a difficulty in deciding on a name is being caused by a flaw in the engineering of the code.

Code that breaks the Single Responsibility Principle will be difficult to name because it requires a longer description to communicate all things it is doing.

Code that doesn't have a well defined purpose will be difficult to name without resorting to words like "manager".

If your having problems naming something take a step back and ask yourself what would make this easier to name? The chances our the answer to that question will highlight a problem with the construction of the code and may point to a potential improvement.

Comfortable in Your Domain

Software generally exists within a domain, whether it be a retail domain, a financial domain or a scientific domain.

This domain is likely to have its own language of terms that convey meaning to anyone working within it regardless of whether or not they are a developer.

Its important that when the code and the domain in which it exists interact that the language of the domain is maintained.

If you were to describe what a piece of code is doing to a non-technical colleague they should be able to derive meaning and context whenever these domain terms are mentioned regardless of whether or not they understand the techie speak in between.

If for example "shipment" has a well defined meaning within your domain then it shouldn't be called "order" within the code base.

This will help form a ubiquitous language that enables everyone in the team to have a meaningful conversation about implementation.

The Outcome not the Journey

As with many aspects of development naming should be about outcomes and not implementation.

It is very easy for unnecessary detail about implementation to creep into the naming of a method or a variable.

This can often confuse the reader of your API but more importantly because there is no direct linkage between what you call something and what it does it can become misleading.

A simple example would be a variable called "ordersList" that after refactoring is no longer implemented as a list.

Many things in software engineering that on the surface appear easy can become complicated due to sub-optimal engineering practices.

In these instances its important to listen to the voice inside that tells you that doesn't seem right.

This voice can be triggered by bad names or an inability to think of a name so rather than increase your stress levels by racking your brain for a better name take a step back and re-evaluate the code in front of you.

A name isn't just for identification its also valuable to communicate your intent and to form the basis for the documentation of your code, with that in mind don't worry if it takes a bit of time.