Naming is one of the greatest challenges in software. There’s even a quote by Phil Karlton around that idea, as follows: “There are only two hard things in computer science: cache invalidation and naming things.” What makes naming so hard? To answer this, it’s important to understand that a piece of software is really just a translation of a domain-specific idea into code. Therefore, programmers need to spend time understanding domain concepts and interactions, not only at the surface level, but also at levels users can’t see.
Imagine yourself naming every concept and interaction in your body required to read this post, let alone this sentence. Reading this text requires a medium by which text is transferred to your eyes. That medium is light, which writes the text to your retina. The brain then somehow collects and processes the text using pattern recognition. You also need to remember the context in which you read the text, so short term memory is involved. I’m sure there is more to it, but I’m no expert in this area, so I’ll leave it at that.
Obviously, people normally don’t need to worry about all of this when reading. People simply read, and that’s the end of it. Programmers, on the other hand, need to dive into that level of detail, and they need to come up with names for all of it. Of course, it won’t be like this example where an understanding of physics and neuroscience is required, but it is still difficult, especially when you realize naming and implementing logic require different hats.
This brings us to poor naming, which every developer knows so well. I’ve seen cases where a concept, X, was named after itself along with “XUtility” and “XManager” variants. I’ve even witnessed code in which variable names were so meaningless, they might as well have been named “variable1″, variable2”, etc. This begs the question: Why are so many concepts so poorly named?
Here are a couple plausible reasons. For instance, programmers tend to focus much of their time on getting things to work. As I said before, coming up with names and implementing logic require different hats. It can be difficult to do both at the same time. Therefore, programmers will initially create vague names as a shortcut in order to churn out as much code as they can to create something functional before going back to find better names. However, they often forget to do the latter once they find the satisfaction in getting something up and running.
Another reason is due to harmful naming conventions, typically names ending in “-er”. I’ll call this category the “ER (emergency room) names”, since it tends to poison developers. They include “controller”, “manager”, and “helper”. Another harmful word that fits in this category, but does not end in “-er”, is “utility”. These words suggest a lack of domain understanding and are inclined to yield structures that conflate multiple concepts into big blobs. They are also words used out of habit, and detract developers from the mindset necessary to properly deconstruct a domain at its joints.
The first reason is actually quite simple to deal with if there are no premature abstractions. The solution is already there in its rawest form, so at that point, it’s just a matter of refactoring. Of course, the refactoring must be done properly so as to decompose the domain into its correct abstractions, which yield good names.
The second reason, on the other hand, is a more serious problem because of the procedural mentality that comes with it. Believing that a domain has “helpers” and “controllers” prevents developers from seeing components as they really are within their respective domains. Maybe the domain has Repositories. Maybe it has Constraints. Perhaps it requires Syntax and a SyntaxTree. What about Keys? Parameters? These kinds of concepts tend to be missed when thinking in terms of the ER names. Code becomes less reusable, and its structure becomes warped because it contains the wrong abstractions.
So how can we fix this issue with bad naming? To start, we can do our best to avoid ER names, which forces us to really understand what our domain is trying to tell us. Doing so allows us to first understand the meaning behind every interaction before finding the appropriate words. In contrast, defaulting to ER names, without first understanding the domain, skews the domain’s original meaning because its meaning is incorrectly drawn from the wrong names.
For example, this Wikipedia page describes the notion of a helper class using the PrependHelper class. PrependHelper provides three different ways to prepend text to another piece of text, namely “Meow meow “, “Woof woof “, and “Wooh “. There are a couple issues with this implementation. [1] The first involves the addition of more methods for every prepending variation. The second is primitive obsession with the String argument. There is clearly another concept revolving around that argument and the different prepended values. We don’t know what it is, but it doesn’t matter. Just by looking at the code, we can find a more meaningful structure that supports the concept and renders the helper class useless.
Of course, there are words that naturally end in “-er” such as “publisher” or “answer”, but to reemphasize, the point is to understand the domain and its interactions in order to derive the right components to which truthful names can be assigned. Even if the names aren’t perfect, the structure will be more in line with the domain, which is most important. It is much easier to change names as opposed to the wrong structure.
Hopefully, this helps you think twice about naming. It’s easy to default to ER names, but resist the temptation. Find truthful names that embody the essence of the domain. Take note that good naming isn’t a silver bullet. Other design methods, such as proper refactoring, are necessary for the identification of the right abstractions, but it will orient you on the right path towards that goal.
Footnotes
[1] There is even a third issue regarding side effects. It is not obvious to the user of this API that an exclamation mark will also be appended to the text. However, this is a topic for another day.
eatsleepios 