Quality of code — Nomenclature

Nomenclature refers to the naming entities in your code (variables, functions, methods, classes, etc.).

Using the proper names for all your entities is critical in making the logic in your code clear and intelligible to other developers who will read your code — and even to yourself if you have to read your own code several weeks or months later.

Consider the following example (admittedly extreme):

let x = new myClass();

and

let user = new User();

The first line tells you absolutely nothing. The second tells you the code is dealing with a new instance of the User class.

Always take extra minutes to find the appropriate names.

Danger

If you don't know what to name a variable, function or class, chances are that your design is flawed.

Use proper English

We code in English, so check the spelling of words and the grammar of word combinations. Eg separate not seperate.

Avoid typos (eg ipnut instead of input). Seeing this in the code is a sure sign that you did not review your own code.

Never use abbreviations

Abbreviations may make sense to you, but may not make sense to other developers, or even to you in the future. Avoid them and always use the full word.

Examples:

Good	Bad
account	acc
message	msg

Name variables for what they do, not what they are

Generally, variables should not be named after their nature, but based on their function in the block of code in which they are used.

For example, assuming a function to send an email:

# bad
function sendEmail() {
  let user = getUserById(/* some id */);
}

# good
function sendEmail() {
  let recipient = getUserById(/* some id */);
  ...
}

Here the second version lets the reader know that the variable refers to the recipient of the email being sent, and is therefore better than the first version. That the variable is a user is indicated by the getUserById method, which is expected to return a user.

Nouns vs verbs

Variables and classes should be named with nouns: user, EmailService.

Functions and methods should be named with verbs: sendEmail, getUser.

Singular vs plural

A variable representing a single entity should be named in the singular (eg let user = getUserById(id)).

A variable that represents a collection of entities should be named in the plural (eg let users = ["john", "mary", "mark"];).

Compound words

Use 1 word instead of 2, 2 words instead of 3.

Sometimes it is necessary to use compound words to remove any ambiguity in the variable name, such as billingAddress va shippingAddress.

If the context is not ambiguous, ask yourself if 1 word will do. If dealing with billing only, then address may be enough.

Follow usual rules of the English language: specificity decreases from left to right: billing Address vs shippingAddress are 2 types of addresses. emailNotification and smsNotification are 2 types of notifications,

Acronyms

An acronym is a word or name formed from the initial components of a longer name or phrase, usually using individual initial letters, as in NATO or EU, but sometimes using syllables, as in Benelux, or a mixture of the two, as in radar. --- Wikipedia

Check the style guide for the language used. If it contains specific rules for acronyms, follow them.

Otherwise, treat acronyms as words, and use the usual case employed to write them in ordinary English.

Acronyms made up of the initials of words (FTP, SSH, SMTP) are always written in uppercase (the first initial may be lowercase to follow the rules for variable names).

Acronyms made up of syllables (WiFi) are treated as words with their first letter in uppercase (again, unless the rules for variables require that their first letter is lower case).

Acronyms that have become words (eg radar) should be treated like words.