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:

• utils
• lib
• tools
• misc
• etc
• common

Whenever I see common, I’m very tempted to commit additional packages named rare, epic and 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 what those 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 category of ThingDoer names, like:

• Executor
• Manager
• Visitor
• Transformer
• Factory
• SyncService

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 LibraryBooks.

• -Data
• -Info
• Entity
• Set
• Node
• Graph

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 Data or 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 PetNetworkGraph simply PetNetwork, or even more tersely, Pets.

Coordination problems

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
• Megazord
• 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.

Comments are welcome at this thread on Hacker News!