Naming Conventions In Javascript

Introduction

Labels and names are everywhere. It is one of the ways for us to recognize something. And if the name is not enough, we would describe the thing and make it understandable for others. But imagine you have only a word to use for the identity of a thing then it has to be descriptive or at least one should know what to expect.

In this article, we discuss why we need naming conventions, what are some of the common patterns to use, and how it helps in code quality.

Naming Conventions

We can divide this topic into two parts for a better understanding

Style Guide and Standards
Finding a good name

Style Guide and Standards

Integrating code formatting tools and linters is the workspace a common practice for developers. We even have built-in code formatters in VSCode. It takes care of formatting our code to look readable and standard, detects errors, assures following style guide, auto-completes and more. However, it can not assure the actual quality of the code, and whether or not it will work as you intended.

Similarly, for naming, we do have the standards, do's and dont's and the best practices that can be followed and it makes it a lot better to just by following these standards.

Robin Wieruch has a great post about Javascript naming conventions which is really useful as a cheat sheet or to provide a reference to others as well in code reviews or in general.

Google javascript style guide has a whole topic on naming, which will cover almost everything you need to know as far as the standards go. This is a more lengthy resource than the previous one but it is in a fairly compact and precise manner and is easy to understand.

Following these resources will make a real difference for the code quality. It will make the code more readable, consistent across the codebase, more predictable, cleaner and easy to review.

Finding A Good Name

Even when following the standards and style guide for naming, it is still possible to write some pretty bad names.

We are free to name our variables and functions how we'd like to, there is really no limitations or hard standards present. And as long as you work on a solo project or a small codebase, it would be perfectly fine to have no stress on this topic.

But better naming is certainly important and could affect the developer experience when it comes to maintaining large applications, working in a team, or contributing to open-source.

Here are some of the best practices that I have identified

No single-letter name

const onChange = (e) => console.log(e)
// e stands for event, element or error?

No single word name

Using a single word leaves a lot of meaning to guesswork and assumptions.

// avoid
let template;

// instead use
let templateID
let themeTemplate
let templateTitle
let templateSVG

Count

Use singular or plural names based on the count of it's content.

// avoid
let selectedBookID = [3112, 332]

// instead
let selectedBookIDs

Re-evaluate the name after writing the code

After writing the code, we can often find better clarity and be able to describe it better than we could before it was written down. That is a good time to revisit the name if necessary.

Avoid the use of "data" in the name

Calling some data, "data", is like calling a person "person" instead of their name. Still, the word data is used a lot in naming. It is okay to use when the "data" is really complex to describe, but trying to avoid this word could lead to a much more descriptive name.

Specify the type of content

Specifying the type of content such as list, object, number etc. helps us to know what to expect and how we can use the variable or constant.

// avoid
const countries

// instead
const countryList
const countryDetails

Group relevant data

// avoid
const instagramLink
const twitterLink
const youtubeLink

// instead
const socialLinks = {
    instagram: '...',
    twitter: '..',
    youtube: '...'
}

Avoid redundant information

// avoid
const imageList = {
    userImage: '..',
    adminImage: '...'
    ...
}
// instead
const brandImageList = {
    user: '..',
    admin: '...'
    ...
}

Add context

// avoid
const userActions

// instead
const userReduxActions

Get more specific

// this is okay
const getUser = ()=> ...

// this is better
const getUserByID = ()=> ...
const getUserByEmail = ()=> ...

Easy to import

Make sure the name makes it easier to auto-import the variable. Using some consistent patterns for naming can also make it more predictable and convenient to find or auto-import.

// examples
type BookDetailsType

const BOOK_CATEGORIES

Avoid duplicate naming

Avoid duplicate naming, even if they exist in completely different modules and are properly sorted by directories.

// example
let CATEGORIES // in books module
let CATEGORIES // in music module
let CATEGORIES // in videos module
// and so on.. Even though these variables exist in isolated modules but all of these will be part of the global search result. It prevents us from being more specific with the operations we try to perform (find, debug, replace etc.)

// instead we can
let BOOK_CATEGORIES
let MUSIC_CATEGORIES
let VIDEO_CATEGORIES

Describe functions with verbs

// examples
const getBookDetails
const formatDateByRegion
const setDefaultUserState
const generateRandomID

General vs specific names

Only use generalised names when a function or variable is usable generally and not only in a specific use case. If it is not usable across multiple modules without any modification, then opt for a more specific name. This lets others know when they should try using your function etc.

Meaning > Length

Hard to understand name can cost us more than a longer name. However, it is important to keep the name short.

// example
const minToHrs // not searchable, doesn't suggest it is a function

// instead
const getHoursByMinutes // clearer, easy to remember/pronounce, predictable parameter and result

Describing the data type of the value

// this is okay
const selectedBook

// this is better
const selectedBookTitle; // seems like a string.
const selectedBookID; // should be a number!

Identifying patterns or rules for naming different types of constants/variables

Finally, I would like to encourage you to identify more of such patterns or rules to follow, that could be specific to your team and codebase.

E.g. Adding Type at the end of all typescript types. It will prevent clashing with the same name that might be used for a variable or constant and it makes code review easier.