Names to avoid in Software Engineering
An incomplete list of poor names for libraries, modules, projects and teams
by Danver Braganza on 2021-01-24
There's an old joke that says the two hardest problems in Computer Science are cache invalidation, naming things and off-by-one errors. Now, giving good names is as much an art as a science, and there are many different schools of advice. When it comes to variable and function naming, Rob Pike's notes on C Style capture the essential goals of good naming practice. However, the Tao of Naming is going to be a contentious topic, and I have no interest in opening that can of worms today.
Names that stink, however, are much easier to spot. Here is an incomplete list of names that should give you pause if you ever encounter them in the wild. Some of these bad names you can fix with just a simple commit. Some of these names indicate a much deeper problem, that will require you to investigate whether the object that bears that name should actually exist as one object at all, or if it must be refactored or reorg into different units.
File under M for Misc
Most programming languages offer developers a way to group collections of similar functions and types into software packages or modules. For some programmers, the ability to have a place to put code that's shared in one place is all that they want from this feature, and they approach code organization with the same amount of thought as their second-from-the-bottom kitchen drawer.
This is why you end up with software modules with names like:
Whenever I see
common, I'm very tempted to commit additional packages named
legendary, and have the contents of each of them be just:
# You must reach a higher level to use this code
There's nothing wrong with putting code in a misc place temporarily, while you
work on it. But when you find that the code is already being reused by different
components in your project, it's time to put a little effort into categorizing
tools you're stuffing into the drawer are, so that other developers
know to look in there when they need it.
The ThingDoer is a thing that does something
When developers adopt design patterns they picked up from textbooks, college
classes or blogs, we can sometimes forget to make the name relevant to the
codebase or task at hand. Perhaps the developers put in a little more
abstraction than they should have into the code. Or, there might be a class that
could just have been a function or a for-loop. This is where we run into the
ThingDoer names, like:
Such names might be appropriate for superclasses and interfaces but are not great matches for business logic. If these classes genuinely need to exist, at least consider including more context about what ThingDoer does, or how it does it, in the name.
Watch out, I'm using Computer Science!
My conjecture is that developers with an academic background are susceptible to
the trap of naming classes after concepts in computer science. Classwork focuses
on teaching core abstract data types, without introducing any real-world
embellishments. However, in real-world situations the fact that your
LibraryBooks are a
Node in a
Graph is often less important than the fact
that they are
Everything is data. I haven't thought through whether I agree with that
statement philosophically. However, when you're programming, everything is data.
Therefore, adding the word
Info at the end of a class or variable
name is free of any semantic content.
Similarly, any references between objects in your programs will form a graph, by
definition. Is there something specifically Graph-y about your class, so that
everyone needs to be reminded every time they type it? In the instance of a
purpose-built graph library, that is definitely the case. For the rest of us, we
can name our
PetNetwork, or even more tersely,
Communication and coordination is one of the hardest parts of getting a single group to do something new, and that is especially true for engineering. This effect compounds drastically as the number of groups involved grows. The next names are not specifically bad names, but signify projects that should be treated with care.
- Project Voltron
- Any musical supergroup
- Any project named after an Anime mecha that combines into a bigger mecha
These names are usually attached to an effort requiring multiple (more than two) separate teams to coordinate in some deep way. Perhaps the goal is to bring each of several teams on legacy platforms onto the new standard software. Or maybe these teams now all need to share data, and build pair-wise data integrations between all of them. You can probably think of a few examples yourself.
Just like the Power Rangers, this project can succeed if it is run with teamwork, strong leadership and technical maturity. Nevertheless be on your guard when you see a Project Voltron.
This team has an unspecified goal
The final category I want to touch on today is something that I don't yet fully understand myself. Engineering organizations of a sufficient size naturally break into sub-teams that are tasked with specific business functions. Sometimes, among them, we find a team who is meant to be "closest to the code", the "most technical of them all". They are responsible for a grab bag of things, such as developer experience, code standards, performance and libraries. And they are usually called something like:
- Platform team
- Core team
- Core Platform Team (true story)
I don't quite know what to make of this team. I've worked on a few Platform teams myself, and my experience there has generally been very pleasant.
However, The Phoenix Project, changed my thinking around how engineering teams deliver value. Rather than committing to large pre-planned projects, it is better to deliver value in small increments. No value has been created until something is in the hands of a customer, and so-called Work in Progress represents a large liability on the sheets of the business.
Based on this, I've now grown skeptical of whether confining engineering talent to work on "the Platform" without specific business objectives is wise.
In Don't Call Yourself a Programmer, Patrick McKenzie quotes Peter Drucker on the difference between Profit Centres and Cost Centres. In every business, some parts of the organization directly make the money, and the rest of the business spends money, supporting them. Patrick admonishes professionals to be attached to the former rather than the latter.
I am concerned that Platform Teams generally read as cost centers to outsiders. Even if the Platform Team delivers a piece of technology that is critical for a product launch, the product team is the one getting the shout-out at all hands. This is why I am tentatively adding Core Platform Team as another name to avoid.
Other articles you may like
- Estimates, Design and the Payoff Line How inaccuracies in estimation lead to a systematic undervaluing of the importance of Design
- Distributed Circuit Breakers at Hipmunk How we implemented Circuit Breakers at Hipmunk to automatically deal with third party outages.
- Misapplying LazyRecursiveDefaultDict A cautionary tale of how I misapplied the wrong software tool to a problem, and what I've learned from it.