Wide Scope Narrow Scope
+-------------+-------------
Function | Short Name | Long Name
+-------------+-------------
Variable | Long Name | Short Name
+-------------+-------------
I can’t quite explain why this works
I'll take a shot...
The general principle uniting all 4 quadrants of the table is: "Use names just long enough to be clear, but not longer."
Here's an illuminating exception to the heuristics: The use of the very short global "DB" for database.
We are really trying to balance two competing goals:
1. Brevity -- Don't explain what I already know. You mention this in relation to a tight loop variable: "I bet you didn’t need me to explain dL stood for Drivers License. It might have even annoyed you if I had spelled it out."
2. Clarity -- Don't confuse me. Don't make me look something up to figure it out.
Maximize brevity while retaining clarity.
Clarity is related to frequency of use. This relates to your comment: "How come the jQuery constructor feels much more natural than the native version? document.querySelectorAll('#appContainer')". It is annoying because we use it all the time... we don't need or want a verbose description.
If the thing is used everywhere, and especially if it is a general convention, assume familiarity. Sure, someone might be confused by "DB" the first time they ever see it, but it will quickly become part of their lexicon and remain so through repeated exposure. However, the same cannot be said for "CGTAO" as a stand in for "cudaGetTextureAlignmentOffset". In that case, the long form is what I want.
We handle these principles effortlessly with our use of "he" vs "John" vs "John Smith" vs "the John Smith you went to highscool with" but for some reason have trouble with them when writing code.
It's all about managing entropy. Less surprising means you can use fewer letters. More surprising means more letters. That shouldn't be too controversial.
The part where it gets tricky is when a concept is widely used, but is a complex concept. What if you have dozens of calls to cudaGetTextureAlignmentOffset in a function, and hundreds in a codebase? Heck, even CUDA is an acronym, Compute Unified Device Architecture.
There's a similar complication when you have several of these big names with slight differences. Made up example, say you also had cudaGetTextureAccessKey, cudaGetVectorAlignmentOffset, etc. I actually find these sometimes worse than the initialisms, as my eyes skip over these long names. The acronyms (CGTAO, CGTAK, CGVAO) have a higher ratio of different letters to total length. But then obviously the abbreviations are very opaque.
> It's all about managing entropy. Less surprising means you can use fewer letters.
I like this framing.
> The part where it gets tricky is when a concept is widely used, but is a complex concept. What if you have dozens of calls to cudaGetTextureAlignmentOffset in a function, and hundreds in a codebase?
You have to predict the knowledge of the developers (current and future) working on the system, and let that guide what you can assume. This is necessarily an art and you'll miss the mark sometimes. One approach is to always be overly verbose, but this is too simple: it destroys readability when practiced without restraint.
> There's a similar complication when you have several of these big names with slight differences. Made up example, say you also had cudaGetTextureAccessKey, cudaGetVectorAlignmentOffset, etc.
One technique here is to introduce a namespacing object/module/<whatever you call it in your language>. So something like "cuda.textureAccessKey", "cuda.vectorAlignmentOffset", etc. Sometimes repetition of a long name is the least of all evils, sometimes it's not.
Agreed. As with all rules there are always exceptions. I say this applies to concepts that are ubiquitous across unrelated codebases. id, repo, min, max, and enum are some that come to mind. Otherwise, all business domain terms should always be spelled out in full in the same way people refer to them in speech (ie, their ubiquitous language). So the only time acronyms are ok here is if that is how people talk about the particular term in every day speech (like "sku" instead of "stock keeping unit").
The general principle uniting all 4 quadrants of the table is: "Use names just long enough to be clear, but not longer."
Here's an illuminating exception to the heuristics: The use of the very short global "DB" for database.
We are really trying to balance two competing goals:
1. Brevity -- Don't explain what I already know. You mention this in relation to a tight loop variable: "I bet you didn’t need me to explain dL stood for Drivers License. It might have even annoyed you if I had spelled it out."
2. Clarity -- Don't confuse me. Don't make me look something up to figure it out.
Maximize brevity while retaining clarity.
Clarity is related to frequency of use. This relates to your comment: "How come the jQuery constructor feels much more natural than the native version? document.querySelectorAll('#appContainer')". It is annoying because we use it all the time... we don't need or want a verbose description.
If the thing is used everywhere, and especially if it is a general convention, assume familiarity. Sure, someone might be confused by "DB" the first time they ever see it, but it will quickly become part of their lexicon and remain so through repeated exposure. However, the same cannot be said for "CGTAO" as a stand in for "cudaGetTextureAlignmentOffset". In that case, the long form is what I want.
We handle these principles effortlessly with our use of "he" vs "John" vs "John Smith" vs "the John Smith you went to highscool with" but for some reason have trouble with them when writing code.