Descriptive names considered harmful.

Accurate labels are hard.

I often see this call to action: “Please, engineers, name your services/repos/libraries more descriptively! I know it’s fun to name your web crawler after the giant spider from Lord of the Rings, but it makes it so much harder for outsiders when we have to remember what Shelob is. Just name it InternalWebCrawler and put a fun picture of a spider in the README or something.”

No. Unironically, no. This is a bad idea.

See, the scope and purpose of something changes faster than its name can. For fun, I did a search on Github READMEs just now for the phrase “despite the name”. About 20,000 results. Here are a few from the first page:

• django-htmlmin: HTML minifier for Python frameworks (not only Django, despite the name).
• plugin-update-checker: Despite the name, it also works with themes.
• svox2: Despite the name, it’s not strictly intended to be a successor of svox.
• CO_Cron: Despite the name, uses node-schedule rather than cron.
• TensorFlow Infra Validator: Despite the name, does not validate the infrastructure being used to run TensorFlow.

That last one is a particularly cautionary tale. TensorFlow is in heavy use by people developing machine learning systems, and from the README one gets the sense that at least a few them were lulled into a false sense of security by that name. Hope none of those people were working on the AI in your car.

I’m probably being overdramatic there, but I hope my point is clear. “Descriptive” names don’t create transparency, they create the illusion of transparency. If you see that something has the name OrderStatusService, you will instinctively assume you know what it is and does, and you will probably be wrong.

(Even worse are those ubiquitous diagrams everybody uses to communicate about software, where there’s a box labeled OrdersService with an arrow connecting it to a box labeled OrderStatusService. I don’t understand why anybody draws those. You can just say “TheOrders Service asynchronously pushes order ids, ETAs, and statuses to the Order Status Service.” If you draw a diagram instead, anybody who wants to believe that the data flows in the other direction, or is synchronous, or is different data, will look at the diagram and see confirmation.)

Now, if a name is going to be easily changeable forever, please do make it descriptive. I’d much rather maintain code where the variables look like numCols and numRows than i and j. (Just, for the love of God, if you change the meaning, also change the name). But if a name is going to serve as, in any sense, an identifier, something that will point at a big complicated thing from many places far away, make it an opaque identifier. You get similar advice in database schema design — if your user’s email address can change, don’t use their email address as a foreign key in your database. Use a number or a random string instead. Something immutable.

In the world of humans, numbers and random strings aren’t friendly identifiers. Instead, here are my suggested guidelines for a name.

• Names should be easy to remember and easy to spell.
• Names should not relate too much to the domain you’re working with. It might feel cute to name part of your zoo administration software “Tiger”, but eventually somebody’s going to be searching for “tiger” in your log files and seeing lots of irrelevant stuff about actual tigers.
• Names should usually not incorporate your company’s name. If everything at BongCo starts with Bong, it just makes the names longer without adding information.
• Names should make you smile. Yes, you, specifically. You should get a dopamine hit whenever something you created comes up, even when it’s in a sentence like “Shelob has broken again.” Fun is one of the most important things there is.
• Names should not describe what you currently think the thing you’re naming is for. Imagine naming your newborn child Doctor, or SupportsMeInMyOldAge. Poor kid.

Shelob has broken down again (original art with Dall-E)