Thoughts on soft-wa.re

A blog of various opinions and ideas on soft-wa.re development

Demos

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

Naming: Convetions

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 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:

Increasingly Bad Examples:

Function - Narrow scope

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

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 
    };
});

Variable - Wide scope

Think a public database, or maybe color names.

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.

tags: Programing - CodingStyle - NamingConventions - ItDepends