A lot of well-known professionals in the software industry stress the importance of naming elements precisely, based on the currently best understanding of the problem domain. This goes all the way from the central concepts dealt with in the project, down to the naming of variables in the source code.
In the foreword of Robert C. Martin‘s book Clean Code you find this gem of wisdom:
You should name a variable using the same care with which you name a first-born child.
James O. Coplien
One reason is maintenance:
Names in software are 90 percent of what makes software readable.
Robert C. Martin
Since software developers read foreign code prior to understanding it and reading code is much more often done than writing it, it makes perfect sense to follow James Coplien‘s advice.
Management and the Urgency of accurate Names
It is often difficult to explain this importance to the management. They want to get things done. Starting a project, maintenance seems to be a beast on the horizon that can be dealt with later. So the technical debt is raised with the first key strokes on a new project.
Names in a software projects have basically two goals:
Control
Naming things is to control them.
Names are the most important attributes of things and events.
Jaroslav Tulach
Perception
Here is a story of the London Zoo that shows the significance of names:
The Zoological Society of London tried to find out, which animals are the most liked by the zoo visitors. They gave each visitor a stack of postcards, each showing a single animal. The stack should be prioritized with the most liked animal on top and the least liked at the bottom. The other day the experiment was repeated, but this time the names of the animals where printed on the cards.
While on the first day a cute little animal made it to a front position, a nasty snake was voted to the bottom. It turned out that after knowing that the cute little animal was a kind of rat and the snake was called Royal Python, the ranking was quite different on the second day: The Royal Python was higher ranked than the nasty Opossum.
Source: Richard David Precht, Warum gibt es alles und nicht nichts?, paraphrased and translated
Names build images and advance expectations. They make how we look at the entities they define, how we assume to handle them and expect their behaviour in response to our actions.
This is also true in the field of software development. If you speak about a test mock and really mean a fake object, this can be confusing to the listeners (at least for those that have read xUnit Test Patterns by Gerard Meszaros). Developers may watch out for verification methods in the mock, but since it is a fake, they won’t find them.
If you call a database user database, but you store products in it, this is confusing, too. Developers will try to store user in the database, but won’t find a table that fits. Other developers might actually search for a place to store products, but won’t have a look at the tables of the user database.
So names make a difference: They control how things are perceived.
Expectations
A repository is expected to store things of a given type. An action listener is expected to listen to actions, a factory is expected to produce something. A button is expected to be pushable, a display to be able to show information.
So names make a difference: They control how things are used.
Accurate Names
You have to find an accurate name for a domain object, or how Mark Twain puts it:
The difference between the right word and the almost right word is the difference between lightning and a lightning bug.
Mark Twain
If the team has to guess names, since no domain expert is available or equally worse, the domain expert has no names for the concepts in the problem domain, there is the danger for the development team to constantly revisit the names of their types without getting any real ground.
It is often more easy to recognize that a given name does not fit, but it is sometimes very hard to find the correct term. But in the end, if you still have not found a name that fully expresses the essence of an entity, you have to go with what you actually made up and repeat your endeavour of finding a matching name until it eventually fits, paying back the technical debt.
Scope
White Spots and Uncertainty
Naming things raises above the source code level and goes deeper than just maintenance issues. It is also about the scope of the project. If you cannot define the scope of the project, name the central pieces, it is like a 19th century map with a lot of white spots.
Source: Wikipedia
The white spots are discomforting. One does not know what’s inside. It’s a source of danger. Cartographers depicted such uncertainty with the phrase “Here be dragons“. So it is hard to comprehend the target and scope of the whole venture. Every white area is a risk for the team to misunderstand something or make something up that is not true at all.
Source: Wikipedia
Killer Joke Pattern
Management sometimes underestimate the power of their technical team knowing precisely what the intended goal of a project is. I often see that the management appoints partial tasks to individuals without any of them understanding the big picture. This reminds me of Monty Pythons‘ Killer Joke (you may watch this as a video on YouTube), where each member of the translation team was given only a fragment to translate in order to not get killed. Maybe this would give a nice name to this “anti-pattern”, not telling the team the whole story: Killer Joke Pattern. 
Scoping the Project
So what to do to tell the whole story? Alistair Cockburn advices us to use outermost use cases. This use cases, usually a handful for a system, define the whole scope of the project.
These outermost use cases are very useful in holding the work together, and I highly recommend writing them [for the following reasons:]
Alistair Cockburn, Three Named Goal Levels. Writing Effective Use Cases
- They show the context in which user goals operate.
- They show life-cycle sequencing of related goals.
- They provide a table of contents for the lower-level use cases […].
The uses cases map the scope of the project and give these maps a name to control them.
So the intention to give scope to a project also is a form of the desire to be in control.
Conclusion
Names are essential since they provide scope and control the artifacts having a name. In the next post, called On Naming, we will discuss how to find names and use them consistently in our projects.
