I’ve been thinking about naming recently, specifically the naming of new systems. It’s tempting to think of naming as trivial, but it really does matter. In a technology driven organization, names are part of how you communicate about the purpose and nature of your systems. And that communication matters more as the number of people and systems grows.

Here are a few rough guidelines to keep in mind.

Avoid minting new names if you can

Every name that has to be remembered is a drain on peoples’ mental space. As such, sometimes the best strategy is not to name something at all, but instead to piggyback on an existing name.

A good example of this at Jane Street is catalog, an in-house pub/sub system. Catalog has many related systems, including the catalog metadata server, the catalog browser, the catalog logger, and the cateye monitoring system.

By sticking catalog somewhere in the name, the user is given a good starting point for understanding the system and what it’s about. In the case of catalog, we’ve even embedded many of these components as sub-commands of the catalog command line tool. This is a useful trick, since it makes these pieces easier to find.

We’ve recently tweaked Core.Command, our command-line parsing library, to make it possible to embed completely separate executables within one unified command-line interface, so that, say, catalog logger could invoke a different executable than the catalog command-line tool itself, meaning we can get the unified discoverability without tying together the release process.

Names should be informative

Your starting point for understanding the nature of a system is often its name. They show up all over the place: documentation, machine names, mailing list names, source directories, config files, emails, and face to face conversations. A name is an opportunity to help people in all those contexts understand what your system does, and you should make the most of that chance.

There are two basic ways to pack information into a name: making it descriptive, and making it mnemonic.

Descriptive names are ones that directly say what the system is for. For example, with a little Jane Street context, it’s not too hard to guess that the activity-cache is a database that caches a view of our trading activity, or that the entitlement-monitor is a tool for monitoring the entitlements that users have for seeing marketdata.

Mnemonic names, on the other hand, are names that give you a mental hook that helps you remember what a system does, without being enough to tell you the meaning. Mnemonic names are less informative, but they’re often shorter, and can carry a more distinct identity than a blandly descriptive one.

A sense of identity can be useful when you need to distinguish systems with similar purposes. We’ve had at least 4 different systems that could have been called alert-monitor. Rather than calling them all alert-monitor, or, even worse, alert-monitor{1..4}, we gave them mnemonic names that carry distinct identites, like watcher, eye, cateye and oculus.

Less common systems should have more descriptive names

When choosing an identifier in code, it’s good practice to pick a longer, more descriptive name when naming a more rarely used thing. You don’t want to waste precious mental space on remembering the meaning of something you interact with rarely. Conversely, short names that are less informative make the most sense for very common operations.

The same principle applies to naming systems. In the systems case, however, it’s a little trickier to think about what it means for something to be “frequently used”. In particular, the audience of people you’re communicating to is more diverse with systems than with code, where your audience is the other developers working on the system. In the systems case, you should think not just about the primary users of your system, but more broadly about the devs, admins, support folk, and really anyone else who interacts incidentally with the system.

Here’s an example. Years, ago, we released a system called gord, which is reponsible for slurping up trading activity from our trading systems and distributing it to other applications. I don’t think it’s a particularly informative name, but it comes up all the time in people’s day to day work life, which means that the information in the name isn’t as important as the fact that it’s short. But a similarly short-and-uninformative name for a rarely used tool is more of a problem.

All this said, descriptive names have downsides too. Descriptives names can be long, and long names impose their own mental cost – at some point people just stop being willing to read the paragraph you’ve embedded in the name. There are also platform-specific limits to name lengths for things like usernames and host names, which matters if you’re going to have users or hosts named after your system.

Practice empathy

Picking names is fun, but you shouldn’t let that lead you to waste other people’s time. We avoid picking cutesy names for identifiers in programs because it makes the code harder to understand and remember, and you should have similar concerns when picking names for your systems.

This doesn’t mean you should never pick a fun name. But you should do so sparingly.

Avoid churn

Names, once chosen, are hard to change. The name gets itself embedded in more places than you can imagine, including other people’s brains. Once it’s out there, it’s often better to let it be than to rename it.

But that very stickiness means you should put some effort into picking a good name, since you’ll probably be stuck with it for a long time.