Should abbreviations and acronyms be avoided as identifiers in source code?

Posted on 08/07/2019 by Ken Gregg

The short answer is yes, usually.

In most coding standards and guidelines I have worked with (and developed) over the decades, the use abbreviations and acronyms in identifiers (e.g., in variable names, function names, type names, class names, structure names, etc.) is discouraged, unless the abbreviation or acronym is extremely well-known and the meaning is both obvious and unambiguous. Some knowledge of the domain can be assumed, but the identifiers should be understandable by a newcomer to the code. Code reviews should flag abbreviations and acronyms that don’t fall within these guidelines.

The overriding rule of thumb is always maximizing the readability of the code for the human reader.

When I was contracting at Bell Labs, I was handed a thick book on my first day there. It contained definitions for all of the many abbreviations and acronyms they used in their work on telephony and communication systems. I thought, “Great! I’ll be able to look up the abbreviations I see in the documentation and code, and will be able to immediately know what’s being referred to. Over time, I won’t have to look them up.” I was happy to receive that book, even though it seemed a bit thicker than I expected. But the first few times I had to actually use this book, I found that each of the abbreviations and acronyms I encountered had between five (5) and twenty three (23) different possible definitions. From the context of use, I could usually narrow down the number of definitions by at least half, but that left between two (2) and eleven (11) possible definitions for each name I was looking up.

Now, for someone who had years of experience reading their specific documentation and code base, it wouldn’t have been as much of an issue. But I was already coming from a telephony background at another company, and had several years of experience with developing and maintaining communication software. I just wasn’t familiar with all of their internal abbreviations and acronyms.

My point is that many of these abbreviations and acronyms used in the code were non-obvious and were ambiguous, unless you were already intimately familiar with the code.

So, again, the overriding factor is always maximizing the readability of the code for the human reader. This, in turn, reduces the cost of maintaining the code. Using a name that the reader of the code must look up in a book or online will slow down the reader, and thus increase the cost of maintaining the code. And if the name is ambiguous, it will slow down the process even more.

Modern development tools with wide display areas, free-form formatting (depending on the language), and high limits on identifier name lengths allow us to be more verbose and as clear as we need to be when writing our code. Remember that the compiler’s view of the code is incidental, compared with the importance of the human readability of the code.

TMAASK, which might mean “Too Many Abbreviations and Acronyms Spoil the Kode,” or it might mean something completely different. I’ll go look it up.

abbreviations acronyms code readability coing guidelines coding standards identifier names variable names naming conventions software development software engineering programming best practice best practices maintainability software maintainability maintaining software source code maintainability