Naming things is one of those two hard problems in computer science, so I don’t pretend to know all the answers, but here are a few things that are red or orange flags to me:
- A commonly accepted abbreviation for a thing exists but instead of using it you invent a new one.
identifier is practically universal;
ident is comparatively awkward.
- You abbreviate an already-short word to save one or two characters. There’s almost never a good reason to abbreviate
- You abbreviate a name but only use the abbreviation once or twice. It’s only worthwhile if the time spent learning the abbreviation is less than the time spent typing it.
- Your abbreviation is hard to pronounce or when spoken aloud is actually longer than the thing you are abbreviating, unless it is already a commonly accepted abbreviation for the thing. May be more important when working in teams.
- You are tempted to abbreviate words just so that they will line up neatly in columns with other words. Other people do this too, right? Not just me?
I try to err on the side of not abbreviating, especially in a public API. But I make exceptions for loop indices (
k), domain-specific abbreviations (e.g.
z), and various short-lived values – it’s more a feeling than a science.
Another exception is when you use an abbreviation to describe a concept that means more than only the word or words you’re abbreviating. In that case, the abbreviation gains a life of its own. I think Rust’s most common abbreviations fall into this category, like
Err. This is vocabulary, in the same category as co-opting an existing word like
Box to mean “owning heap pointer”. It feels different than just abbreviating a word.
One thing to keep in mind is that it’s easier to search your code when it contains full words. I can’t find the code that calculates resonance frequency… Hmm, did I shorten that to
res_freq? Or was it
rf? I don’t remember, it’s been so long…