Jane Street Blog - Notes on Naming

Notes on Naming

Jun 29, 2014 |

5 min read

Share on Facebook

Share on Twitter

Share on LinkedIn

By: Yaron Minsky

I’ve been thinking about naming recently, specifically the naming of new<br>systems. It’s tempting to think of naming as trivial, but it really does matter.<br>In a technology driven organization, names are part of how you communicate about<br>the purpose and nature of your systems. And that communication matters more as<br>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<br>such, sometimes the best strategy is not to name something at all, but instead<br>to piggyback on an existing name.

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

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

We’ve recently tweaked Core.Command, our command-line parsing library, to make<br>it possible to embed completely separate executables within one unified<br>command-line interface, so that, say, catalog logger could invoke a different<br>executable than the catalog command-line tool itself, meaning we can get the<br>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.<br>They show up all over the place: documentation, machine names, mailing list<br>names, source directories, config files, emails, and face to face conversations.<br>A name is an opportunity to help people in all those contexts understand what<br>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<br>descriptive, and making it mnemonic.

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

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

A sense of identity can be useful when you need to distinguish systems with<br>similar purposes. We’ve had at least 4 different systems that could have been<br>called alert-monitor. Rather than calling them all alert-monitor, or, even<br>worse, alert-monitor{1..4}, we gave them mnemonic names that carry distinct<br>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<br>descriptive name when naming a more rarely used thing. You don’t want to waste<br>precious mental space on remembering the meaning of something you interact with<br>rarely. Conversely, short names that are less informative make the most sense<br>for very common operations.

The same principle applies to naming systems. In the systems case, however, it’s<br>a little trickier to think about what it means for something to be “frequently<br>used”. In particular, the audience of people you’re communicating to is more<br>diverse with systems than with code, where your audience is the other developers<br>working on the system. In the systems case, you should think not just about the<br>primary users of your system, but more broadly about the devs, admins, support<br>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<br>reponsible for slurping up trading activity from our trading systems and<br>distributing it to other applications. I don’t think it’s a particularly<br>informative name, but it comes up all the time in people’s day to day work life,<br>which means that the information in the name isn’t as important as the fact that<br>it’s short. But a similarly short-and-uninformative name for a rarely used tool<br>is more of a problem.

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