Preferred naming convention: full words or abbreviations?

1

Hi! What's the preferred naming style in Rust community: full words or abbreviations?

Say, what should I use for struct's field name? deps or dependencies, pkg or package?

I know that rustc / cargo tend to use abbreviations, and than vowels are especially frowned upon :slight_smile: But is this the generally preferred style?

I personally always flip-flop between the two, which is strictly worse then any single style. That's why I am asking the question: to become consistent myself :slight_smile:

4 Likes
2

I prefer abbreviations because it's quicker to type them in phone's touch.

FuncExpr
App
Proc
I18n
L10n
3

What I've found is that as long as it's readable and isn't ridiculous (I.E. size_of_the_data_that_we_store_in_this_struct_and_it_is_not_to_be_edited) it's okay. If you want a standard, then look at other crates and their naming conventions, for example look at some of the most downloaded in crates.io, but be sure to not look at something that is forced to take on another naming convention, such as c bindings or opengl bindings, which have their own special names. Then again, one can even go ahead and look at the standard library, where modules are made with shorter names (std, ops, fmt, ffi, fs etc.) and individual traits, structs and enums have full names, like Add, Option, Result, panic etc.

4

I personally generally prefer full words to abbreviations, because abbreviations are something that, in my opinion, reduces readability. As a non native English speaker, I sometimes find difficult to understand the meaning of abbreviations, and so it adds an additional cost to reading code. Meanwhile, I don't find that abbreviations add a significant advantage while writing code. I often have words in my muscle memory when writing with a keyboard, and I also use autocompletion for types that are multiple words long. Besides, I think the readability advantage trumps the possible writability advantage anyway.

That being said, accepting short-hand names for types is what makes accumulating them bearable, also when reading. Surely AtomicReferenceCounted<Vector<Binary tree<integer64, String>>> is a mouthful to read out...

So I guess your current "inconsistent" behaviour is appropriate... If you want to clarify, I'd do the following:

  • Default to writing out full names
  • Make exceptions and write abbreviations in any of the following situations:
    • Name is a domain specific term, and in that domain, the abbreviation is what is used, to the point that the full form is stranger to read (example TCPIP)
    • The name is to be composed with other names (smart pointer, collection, modules)
    • Users of your library are very very likely to know the abbreviation
    • Full name would be very long
  • When taking such decisions to shorten, document them and the reasons that motivated them.
  • Also document the name of the full form :slight_smile:

Naming is hard :slight_smile: -

6 Likes
5

Rust has a certain vocabulary of abbreviations, e.g. Ref, Vec. It'd be weird to see Reference and Vector, so I'd try to avoid "un-abbreviating" words that are already commonly abbreviated.

1 Like
6

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. id for 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 flag as flg or table as tbl.
  • 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 (i, j, k), domain-specific abbreviations (e.g. x, y, 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 Mutex, Vec, Ref, and 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...

1 Like
7

I mostly start out unabbreviated and than "evolve" the naming. If i would shorten a name when talking about it, then i would also shorten it in code.

I also don't have any qualms using one letter variable names when the name is not important. For example, map(|x| x.len()) is a lot better than map(|semantic_name| semantic_name.len()). I know the semantics at that point, i don't have to repeat it when applying a general operation. Especially if that name pushes a single line method chain over the character limit.

I dislike abbreviations that are hard to speak out loud. In reference to trentj: Imo, res_freq is a good name. Everyone who is familiar with the domain knows what is meant, its easy to speak out loud and resonance_frequency is very long. Since this name is probably used in formulas they will become unwieldy very fast if every variable in them is 15-20 characters long.

Another thought: Information that is encoded in a type of a thing doesn't necessarily need to be documented in the name of an instance of it. This also means that if i feel the need to use very long explanatory names to not confuse my 7 different integers, maybe its time to create some types. That frees the naming for high level concepts and leaves the nitty gritty details to the type system.

3 Likes