JavaScript Clean Code — Naming

Writing clean and easily readable and maintainable code takes some effort. One of the most basic parts of a program is identifiers. To make reading and changing the code easier, the naming of them has to be good.

In this article, we’ll look at some ways to name things in an easy to understand way.

Intention Revealing Names

Names have to have the intention of what you’re trying to define. This way, people will know what your identifier actually means.

Function, class, variables, and constants should all names that show what they’re used for.

For example,

let x;

would be a bad variable declaration because x doesn’t reveal with it’s doing.

We should name it something like:

let numApples;

so we know that our variable actually holds the value of the number of apples.

As we can see, numApples is much easier to understand than x .

Likewise, for arrays, we should name them with meaningful names. For instance:

let list = [];

isn’t a good name because we don’t what list actually holds. Instead, we should write something like:

let fruits = [];

So we know that the array holds Fruit objects.

Avoid Misleading Names

Names shouldn’t be misleading. They shouldn’t be leaving false clues for the reader and lead them to the wrong conclusion about your identifiers.

For example, fruitArray should actually be an array rather than anything else. This is especially important in JavaScript because the types of variables can change and there’re no type annotations to let us figure out what the type is.

Names should also have a consistent convention. In JavaScript, variables are camel case. Constants are upper case and functions and classes are upper camel case.

So we should stick with that and don’t deviate from it. Otherwise, it gets confusing fast and other developers looking at our code can easily miss the different cases.

For instance:

let FruitArray;

isn’t a good variable declaration since it starts with a capital letter.

It should instead be:

let fruitArray;

The consistent convention makes code easy to read and remember.

Meaning Distinctions

To make identifiers distinct, we should name them in a meaningful way.

For example, if we want to copy an array from the source to the destination array, we shouldn’t write something like:

let a2 = [...a1];

since we don’t know what a2 and a1 means. Number series naming as we had above is bad. It doesn’t reveal the intentions of the names.

Instead, we should name them for what they are. So we can write:

let destinationArray = [...sourceArray];

The code above is much clearer since we know that they’re both arrays and we know that we’re making a copy of sourceArray and set as the value of destinationArray .

They’re still distinct and they reveal their meanings.

We shouldn’t add noise words like variable in a variable. It makes the name longer without revealing additional information.

However, adding the type name may be helpful in some cases since we’re always assigning literals to a variable or constant. Since JavaScript has dynamic types, the type can be added to the name in cases that we aren’t assigning literals to something.

Pronounceable Names

Pronounceable name are easier to remember and understand. Therefore, we should name things in a way that is pronounceable.

Also if it’s easier to pronounce, people won’t look dumb when they’re discussing about something with such names.

For example:

let genmdy;

isn’t a good name for a variable that means generated date and time because nobody knows how to pronounce it.

Instead, we can instead write:

let generatedDateTime;

would be much better since it reveals more information and it’s pronounceable.

Searchable Names

Developers often have to search through to add new code and debug. Therefore, it’s important to have names that are searchable by typing in the search box or command line.

This means that variable declarations like:

let a;

is bad since the character a is everywhere in almost all pieces of code. This means that it’s hard to search for it when we need to.

Instead, we should write something longer and more meaningful like:

let numApples;

so we can search for it.

Stick to Plain English Letters and Digits

Plain English letters and digits aren’t encoded in any special way, so it won’t cause problems in different systems and we can easily search for the names.

Also, most languages have English keywords so it’s more consistent with the rest of the code.

It justs taxes people’s brains more to figure out the encoding of characters of different languages. That’s the time that can be used to read and code.

Member Prefixes

We don’t need prefixes are class and function member names since they’re already inside the class. Namespacing them with a prefix is just extra noise. Also, classes and functions should be small enough that there shouldn’t be too many members.

Most people also ignore the prefix and look straight at the name.

Therefore, something like:

let m_description;

isn’t any more useful than:

let description;

It just takes up more space and creates noise.

Naming things properly takes some effort. We have to make identifiers with meaningful names that reveal their intentions. Also, the convention should be consistent to reduce confusion and mistakes.

Identifiers should also be searchable and pronounceable so that people can look for them and talk about them without sounding dumb.

Characters with special encoding also shouldn’t be used to avoid extra useless effort.

Finally, we don’t need prefixes in member names since there shouldn’t be soo many that they need to be namespaced.

The post JavaScript Clean Code — Naming appeared first on The Web Dev.