Naming things is a core part of any programming. Almost everything needs a name and things being named well is an important factor in overall readability. Although coming up with good names may seem easy enough, there are some pitfalls that I see often. Here are ten things to avoid in your naming efforts.
1. Being Too Short
This rule may seem too obvious to list, but it is also broken too often to not list. Names should always be long enough to convey the purpose of their use. If you’re using one or two letter variable names, it has to be only in the most obvious cases. It is perfectly fine to use “i” as the name of the index counter variable in a for loop because we all learn it that way, and that makes it very clear. Most other uses would be very unclear. You have to look back at the assignments to know what is going on. This is not a sign of a good name.
2. Being Too Long
I’ve seen programmers that don’t subscribe to this rule, but it is important. The length of a name needs to stay within reason, because as the length grows, the ability for quick and easy comprehension of the meaning shrinks. I believe that the main reason that these names grow too large is a lack of attention paid to context. As a basic example, a class named Employee doesn’t need a method that returns the employee’s first name to include the word employee. We know that already because of the context. “getFirstName” is much better than “getEmployeesFirstName”. Names don’t live in a vacuum, so you don’t need to have the make sense outside of their context. They are being read within the context of the rest of the code, so that should always be considered.
3. Having Typos and Misspellings
This one seems super obvious, but it happens very often. There are some programmers who like to use copy and paste for everything. This is good for avoiding typos, but what about the cases when you start with a mistake. It happens more than you’d think. I personally prefer leaning towards typing things more. I feel like it improves my comprehension of what’s going on and gives me more angles to evaluate the code. But that’s just my opinion, and there is certainly nothing wrong with copying and pasting, as long as you double-check it. And check the spellings with a dictionary if there’s any chance you get it wrong. That’s just embarrassing.
4. Using Cryptic Abbreviations
Abbreviations are great for shorting words used in names, but this only works if there aren’t alternative meanings for the abbreviation. One of the worst examples I’ve seen of this is abbreviating number to “no”. For example, this is a real variable name I witnessed in the wild: “no_completions”. This one is great because it violates multiple rules. But even without the misspelling, it is completely non-obvious that this contains the count of completions because there is a pretty obvious alternative meaning to “no” other than an abbreviation for number. There are many more subtle possibilities with abbreviations, so the point is to just watch out for them and only abbreviate when the meaning is obvious.
5. Not Following Code Style Standards
Code Style Guides are there for your benefit. These are a great help in making code more readable. They should never be treated as optional or disregarded. Know the standards that your team uses and have enough regard for team members and your future self to follow them. Enough Said.
6. Being Cryptic With the Direction of a Boolean
This one is always very frustrating to me. I’m a big fan of boolean values because of their simplicity. It has the minimum amount of possible values. But that also means if it is not clear you could end up with being as far away from the real value as possible. Think about it, if you have a variable named “switchFlipped” that has a value of false, do you know what it means. If the person who wrote the code thinks one way and the person reading the code thinks another it ends up having the opposite interpretation as it should. This is easily avoidable with names that clearly indicate the direction of the boolean. Good examples are “isActive” or “isDisabled”. These can not easily be confused as the meaing of a true or false value is very obvious.
7. Trying to Be Cute or Funny
This rule might be just for me, as I used to like doing this quite a bit not too many years ago. It is fun when a coworker discovers a little joke you put into a variable name. It makes everyone laugh, and what’s wrong with that. Well, time is the problem. It’s not easy to write a cute name that makes you laugh when you’ve read it for the one hundredth time. It gets real old. Names should be decided based on clarity and not based on humor or cuteness. It is not worth it in the long run.
8. Having Multiple Possible Interpretations
This is a very general rule, but it is very important. There are many examples where the name of something can have a different meaning than you intended. This interpretation may not be obvious to you but to somebody else, it may be the most obvious way to see it. This makes this a great thing for you and your team to watch out for in code reviews. If there’s an alternative interpretation that’s more obvious to somebody else who is looking at your code, than your efforts for clarity have missed the mark. Try to look at your code from different angles and imagine what other people might be thinking, and definitely look for help from your team to make sure that your names are obvious without possibilities that you haven’t foreseen.
9. Not Adjusting With a Refactor
Refactoring is an important part of coding and should happen on a regular basis. Often refactoring a method or sections of methods means completely changing the context. As seen in some other rules, the context in which something lives matters greatly for the name. In particular the length and including unnecessary information. When code gets cut and pasted to a different location, make sure that the names are reconsidered with the new context. Otherwise, rules that were followed with the initial name end up violated with the new context.
A great thing about this rule is that it works in reverse, too. When you notice a name is very long and it needs that length for being clear about its purpose, it is worth considering if it could use a refactor. This goes way beyond the scope of just naming, but it is a good way to pay attention to one red flag for the structure of your code.
10. Not Clearly Revealing the Purpose
This is the most general rule, and the most important. If you think you have followed all the other rules that I’ve listed but the purpose of the variable/method/class isn’t clear, then there is something still missing or off. The names should support the basic goal of glanceable code. When you look at the name of something you should have a basic idea of what is going on immediately. No investigation should be required. Don’t make your team or future-you do a bunch of digging to figure out what the method does, or what the purpose of the field or variable is. The name should reveal it, and do so with a glance. It makes everything easier to work with. It’s worth a second look to make sure that you are getting as close to that goal as possible.
Go Forth and Name Powerfully
I hope that this list has helped to make your names just a little better. Remember to keep you overarching goal of readability in mind and to review your names more than once and from more than one angle. Make good names part of your regular practice and keep on the path to becoming a more powerful programmer. Do you have any rules that you have that weren't covered here? I'd love to see it in the comments.
