Naming: Naming Conventions

They say there are two hard problems in computer science: Caching, Naming things, and off by one errors.

No? Ok.

Let’s talk about naming things. I don’t think it has to be that hard. I have a few guidelines to keep in mind that go beyond the usual suspects. Let’s run through them real quick.

1. Most important words first
2. Consider the scoping

Most important words first.

This is a specific use case of my more general principle “most important thing first”.

Frequently I will see developers write variables as they may speak them, and yes I do think that is good sometimes, the problem though is English grammar isn’t the best. I like Spanish grammar better. In case you don’t know in Spanish you generally place the noun before the adjective, and verbs before adverbs. Everyone agrees this makes sense. The reason it makes sense is because it puts the most important words first.

Consider this when choosing variable names. I like this because it can make your code more readable. Let’s take a look at an example. Let’s take a look a few conventions I have seen in different versions of colors.scss and see which is easiest to read.

Always noun first, Always with a modifier following, align the colons.

:root {
  --gray-white : #FFFFFF
  --gray-medium: #AAAAAA
  --gray-black : #000000
  --blue-light : #48CAE4
  --blue-medium: #00B4D8
  --blue-dark  : #023E8A
}

Always noun first, Always with a modifier following, Always with a modifier, with pure color exceptions, align the colons.

:root {
  --white      : #FFFFFF
  --gray-medium: #AAAAAA
  --black      : #000000
  --blue-light : #48CAE4
  --blue-medium: #00B4D8
  --blue-dark  : #023E8A
}

Modifier first, noun following, with pure color exceptions, align the colons.

:root {
  --white      : #FFFFFF
  --medium-gray: #AAAAAA
  --black-gray : #000000
  --light-blue : #48CAE4
  --medium-blue: #00B4D8
  --dark-blue  : #023E8A
}

Modifier first, noun following, with pure color exceptions, don’t align the colons.

:root {
  --white: #FFFFFF
  --medium-gray: #AAAAAA
  --black-gray: #000000
  --light-blue: #48CAE4
  --medium-blue: #00B4D8
  --dark-blue: #023E8A
}

This is subjective, but for me, in most cases, I think 2 is best.

• I think it’s easier on the eyes,
• If you wanted it to be sorted alphabetically and come out pretty close to something meaningful, 1 would be slightly better than 2, but both would still be pretty good.

I think it should be clear that when you put the most important word first, the characters automatically align themselves, making it easier for your eyes to scan a block of text, and even whole blocks of text could be sorted alphabetically and come out pretty good.

Next time try pushing your nouns to the front of your variables, and your verbs to the front of your functions. Then suffix with your adjectives and your adverbs.

Consider the scoping.

Here is a quick summary.

	Wide Scope	Narrow Scope
Function	Short Name	Long Name
Variable	Long Name	Short Name

I can’t quite explain why this works, but I have two things to back up my claim. First, an appeal to an authority. This is a recommendation from Bob Martin. You’ll have to watch his videos to see it though, a quick search doesn’t turn anything up. Second, a few examples.

Function - Wide scope

Meaning how widely used is it? Consider Lodash and jQuery or maybe some other constructors.

Good Examples:

• _.map()
• $(“#appContainer”)
• new Vue()

Increasingly Bad Examples:

• Something that is pushing the limit of “short”:
  • ReactDOM.render(/**/)
• How come the jQuery constructor feels much more natural than the native version?
  • document.querySelectorAll(“#appContainer”)

Function - Narrow scope

functions that have a super specific purpose should speak for themselves.

• cudaGetTextureAlignmentOffset

I bet you have a decent idea what this function is for. Now it’s especially good for this example here because it mentions the library name, but that may not be best in practice. I don’t want cuda eating up 4 characters everytime I call it. I know we are using cuda! Stop with the branding Nvidia! Keep in mind this isn’t the narrowest scoped function possible, just one of the more narrow ones that can be readily shared. Let’s say I did get my way though and could trim off the cude from the function name what would we have?

    someObject.getTextureAlignmentOffset(offset, texref)

Beautiful.

Variable - Narrow scope

Let’s not be tempted to stick with the previous example. The problem is that function has a wide audience and so do the variables. So shortening them is probably not a good idea. Let’s make something up. Let’s convert drivers licenses into applications.

const applications = driversLicenses.map((dL, i, arr) => {
    return { 
        id: i, 
        userName: dL.name, phone:dL.phoneNumber 
    };
});

• 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. The further away some data gets from it origin the more it will need to be explained. But with one or two lines, one or two characters is probably just fine.

Variable - Wide scope

Think a public database, or maybe color names.

• Css Color Names is tricky because there are good and bad strategies for managing your applications colors. But if you are trying to create names for all 16 million colors your going to need some long names. Good luck keeping all of them meaningful.
• Public Databases: I can say it is 72°F but that doesn’t mean much unless I also specify where and when. Which could be considered part of the name. I know I am stretching this here, but we haven’t gone too far yet. If you wanted to make a public database of temperatures your api might be
• tempsDB.atLocation(48.85827172505176, 2.294531782785587).atTime(946645199)
• tempsDB.atLocation(“Eiffel tower”).atTime(“Midnight”)
• We are definitely stretching the definition of name to encompass that, but I don’t think it’s a stretch to say that we required a very long identifier to specify a piece of data we were looking for that had a wide scope.
• it’s also easy to imagine a config file that would be consumed by an application that would require long names to specify different pieces of data the application would consume.

Reflection

Did you make it this far? I will agree that some of the later examples got rougher, so I do not want to push this as gospel. Just something to consider while you are writing your code. Something that I reflected on as I was writing this is maybe this is a rule of thumb on when it is ok to abbreviate your names. Ok, that kind of works. If you are making a library like lodash or jquery, or another very commonly used function inside your own codebase; shortening that function name might be a good idea; and if you are where a variable is only going to live for 4 lines because you just pulled it from somewhere and are moving it somewhere else, then it might be ok to shorten that variable name.