Bad names are like paper cuts. A single one is unlikely to cause any serious damage, but many put together can cause an entire code base to be scrapped. What’s worse, the effect is often exponentially cumulative. One bad name leads to another, leading to an incomprehensible code base and lots of wasted time.
Thinking about naming forces you to understand your code intimately and to claim every decision made therein. There is audacity in naming. It is art and science and magic. Programming languages are a framework for distributing a problem space across developers. Naming things well is the glue that holds this framework together. It is the transport layer, the basic building block of a team working together.
Toward the goal of efficient, meaningful naming, I suggest the following guidelines. There is some overlap, and not all ideas apply to all circumstances. It is important to own the rules, not the other way around. Sometimes they should be broken, but nonetheless, having them in mind usually steers me toward better code.
Rule 1: A Good Name Argues for a Thing’s Value
A good name reflects why a thing has to exist. Sometimes this means: “What does it do?” Other times it means: “What does it represent?” The point is that it should be specific and explanatory. Assuming a class’ focus is sending a Tweet, a name TweetSender is better than TwitterClient, which in turn is better than HttpPostAgent.
Rule 2: Modifiers Must Be Objective & Permanent
A good name is always true. Adding something like NewX or BetterX is bound to be disputed or eventually be wrong. Rather than say New, use the difference between the old and the new. Rather than Better, explain how it is better or what aspect is, e.g., NonBlockingX and RackAwareX.
Rule 3: Qualify to the Degree of Uniqueness Within Scope
A good name is short and simple. If there is only one thing that does X in scope, don’t name it anything more than X. If you have three things that do X, each should be named for the three scenarios. If your app exists to convert Tweets to SMS messages, Converter is perfect. If you have to convert Facebook Posts and Tweets, then you need to qualify PostConverter or TweetConverter. If you app has to convert Posts or Tweets to SMS or email, then you need PostToEmailConverter, PostToSmsConverter, etc. The point is, in the first scenario, there is no need for TweetToEmailConverter.
Rule 4: Don’t Be Redundant Within Hierarchies
A good name does not repeat itself. The name of a method is always a descendant of the name of the class. If your class is named TweetConverter, you don’t need to name the method ConvertTweet. It is obvious in the class name that this is what the class does. Convert is sufficient or even Apply if you want to be all Scala-y.
Rule 5: If You Can’t Find the Right Name, It’s the Wrong Design
A good name is about solving problems, not designing software. If you find yourself naming something Agent or Delegate, or another noun that indicates a design decision and not a business need or purpose, reconsider why you need that thing at all.
Rule 6: Explicit + Clever > Explicit > Clever
A good name is both explicit and clever. Everyone loves a good metaphor, and programming is ripe with opportunities for hilarious puns. But it is alway better to name things after what they do, not to extend a metaphor that doesn’t help people understand what your code is doing. If you can make it clear why your code exists while still being clever, then that is by far better.
Rule 7: Names Must Be Ubiquitous
A good name is consistent. When you name a thing X, it has to be X everywhere it is referenced. Don’t use TwitterID in one place, and TwitterUserID in another and UserID somewhere else. Pick the best one and refactor so it’s consistent. The more ubiquitous language used across your domain, the better.
Rule 8: The More Important a Thing, the More Important Its Name
A good name is contextually important. Unless you have a really good reason to name an iterator placeholder, then just use I. Don’t spend days considering the perfect name for your logger. But the name of the system is much more valuable to spend time on. The name for the classes and key methods—those have to be considered.
Rule 9: Rename Things When Starting Out, Then Stop Changing Them
A good name doesn’t change once it settles in. When you are just starting to write something, you will name things poorly. Don’t be afraid to rename as you refactor. If you do not do this, your names will be a huge barrier to code comprehension. But once things are stable, after you haven’t had to change the name in a while, resist the temptation to tweak the name just a bit. It may be slightly more perfect, but it will have ripple effects in the code base, and the code will be more fragmented.
That’s it. My nine rules. I’d love to hear what you think, whether you object or have other suggestions.