that which we call a rose By any other name would smell as sweet

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

— Phil Karlton

Many people may have herd this quote, or a variation of, but the basic premise is the same naming things e.g. variables, classes, products/application, etc… is hard.

The question is why is naming so hard? There are a million reasons why that could be but after many years in the software industry I believe I have found the reason why.

It all boils down to ‘pedantry’ on behalf of the developer. Software developers often immerse themselves in the domain of the user in order to help them solve a problem. During this journey they often come across strange quirks of how humans use language to communicate concepts and ideas to each other.

As an example, we all know what a coffee machine is, its the thing that fuels developers. If you say coffee machine 99%+ of the population they know what a coffee machine is. However, if you speak to a developer (with their developer hat on) and talk about a “coffee machine” you would get a response something along the lines of “well technically it’s not a coffee machine, it doesn’t produce coffee, it dispenses ‘coffee’ flavored beverage”.

This pedantry often creeps into the code developers write, the users of the software/application use a ‘technically incorrect’ word to describe something and the developers ‘knowing better’ come up with a more ‘accurate’ word for the same thing that means nothing to the majority of users.

Class CoffeeMachine becomes class CoffeeFlavouredBeverageDistpenser. This is not an issue, if only the (pedantic) developers where involved in creating software but this is not true in modern software development. In the modern world of agile software development users (stakeholders) are a key part of the development process.

What happens is developers start taking about coffee ‘flavored’ beverage dispensers in a meeting and the stakeholders and everyone but the software team are left sat their thinking ‘what are they talking about’ until the inevitable happens and someone releases the software developers are talking about the coffee machine. This usually end with ‘why didn’t you just say coffee machine?’.

The users of the software may use ‘strange’ words to describe things that don’t sit well with software developers but these ‘strange’ words are the language of the domain your are developing in.

Having a shared vocabulary is key to being able to share complex ideas between the software team and the users the software that it is being developed.

If the users call the thing in the corner you are writing software for, a ‘thing-a-majig’ then use that in the code. Yes, it’s not technically correct but when you enviably have to speak to the users to find our new requirements or fix bugs, if you say ‘thing-a-majig’ you both instantly know what you are talking about and when it comes to implementing these new features or fixing a bug you know you need to be looking at the ‘thing-a-majig’ class.

TL;DR;

Naming is only hard because developers try to come up with ‘better’ names for things that users are familiar with. Use the language of the domain you are working in to guide naming, not the inner desire to be pedantic.

Self proclaimed software engineering expert. After years of getting it wrong, I want to guide other on how to get it right.