Abbreviations Suck

For a recent project, I had to work a lot with the express Node.js framework. Abbreviations are used everywhere in the express documentation: req, res, err, etc. As I copied code snippets from the documentation into my project and kept changing the abbreviations into the words they stand for, I figured I could write an article on the subject.

The case for abbreviations

Let’s start with the opposing opinion - why use abbreviations in the first place? There are only two reasons I can think of:

1. Abbreviations are shorter and therefore faster to write
   Although this argument could be completely shut down by stating that every modern code editor has an autocomplete feature, let’s do some math. I’m writing with about 300 keystrokes per minute – time saved writing 5 letters less (e.g. res instead of response)? 1 second. Even if you are writing a lot of code per day, let’s say 160 lines, and let’s assume you’re writing one abbreviation every two lines. The time saved per day would be roughly 7 minutes. In contrast to that there might be dozens of people reading your code in the future. If each of them has to think only one minute longer about your code to understand it because an abbreviation isn’t completely clear, it results in a net loss of time spent. Or even worse: a bug might be caused by a misunderstanding of an abbreviation.
2. Abbreviations are shorter and therefore occupy less space
   There is some truth to this argument in that it’s broadly considered a good practice to keep your line length short (80-120 characters per line depending on who you ask). But I’d argue that although abbreviations might help in reducing the line length, they oppose the actual goal of the rule which is to improve readability.

The case against abbreviations

Now take a look at the reasons why not to use abbreviations.

1. Abbreviations make it harder to understand your code
   Let’s stick with the express framework and take the res abbreviation as an example. If you’re an express guy or you’re working heavily with server response logic, it seems pretty obvious that res stands for response. But let’s assume your project is about REST stuff and all you think about is resources, now res (again obviously) stands for resource. You’re primed for the meaning of an abbreviation because of the context you’re working in.
2. Abbreviations make it harder to be consistent
   There may be dozens of people working on one codebase simultaneously. Everyone of them could have a different opinion on how to abbreviate certain words. The common word options could become opts, opt or maybe just o (I’m quite sure there is a special place in hell for those o guys).
3. Naming things is easier being more explicit
   Naming things is hard. Some say coming up with a good name for a variable or function is one of the hardest things in programming. But it is much easier if you give up on keeping the names as short as possible. Use obvious names like getResponseValues instead of getResVal. Res could stand for Response, Resource, Reserved,… and Val could stand for Value, Validation,… What might seem obvious at the time you’re writing it, may not be that obvious for other people, or even yourself in one year.

Exceptions

I’m not a fan of absolutes and there might be valid cases in which using abbreviations makes sense.

• As a JavaScript developer one exception that instantly comes to mind when talking about abbreviations is e for event. Thats just such a widely used pattern that I hardly can argue against it. All the more important it is to not use e as an abbreviation for error.
• Your team may define a short list of abbreviations of common words everybody has to use. Keep the list short and be very careful to be consistent and everybody is using the same abbreviations. Actually write down the list and teach it to new team members when onboarding them.
• If you’re heavily committed to work with express or some other framework than it might be beneficial to stick to the abbreviations that are commonly used in those eco systems.