Readability: No abbreviations

When you are writing code, it is very tempting to shorten the names of functions and variables when the shortening seems blatantly obvious. All of us have, at some point, written calc_usage instead of calculate_usage; res instead of result; stmt instead of statement; ctx instead of context; etc. The thought goes “well, these abbreviations are obvious, and I’ll be a much faster developer!”

Wrong. You might think you are faster at typing, but you don’t write code in one go and never ever get back to it again. As we have already mentioned, code is usually only written once and is later read many times, possibly by people other than the original developer. At the very least, I’d expect you going over your code once before checking it into your repository. Spending the extra minute it takes to write words in full will benefit you and your readers.

Let me go out a bit on a tangent while being no expert in cognition. Our brain is trained to recognize words not only by reading letters left to right; we see the full word at once, and, unless it is a new word that we have never seen before, we recognize what it is without having to go over all its letters. If you truncate words or remove letters in an attempt to make them shorter, reading the word becomes non-obvious and slows you down. Or, rather, it will certainly slow down other readers of the code — particularly if their native language is not the same as yours.

Examples of bad names? They are everywhere: ffs_fragacct, inblk, siz, cgp, cnt, sump, forw… I wish I was making these up, but they all come from a single file I picked at random from the NetBSD tree. Can you tell what any of these names refer to, univocally?

Lastly, keep in mind that when your variable name is not descriptive enough, you will be tempted to add a comment to clarify its purpose. Don’t. Fix the variable name to not need a comment in the first place!

So, my suggestion: never use abbreviations. Spell out words in full in all your identifier names, and make the names self-explanatory.