How to Write Clean JavaScript Code

Why Clean Code Matters

The case for clean code is not aesthetic. It is about the cost of change. Every hour spent deciphering a function is an hour not spent fixing a bug or building a feature, and that cost compounds as a codebase grows.

The Core Principles

Everything else in this guide is a consequence of these seven ideas. They are not new — most of them come from a body of writing on software design that predates JavaScript entirely — but they apply directly to how you write a function or name a variable today.

Small Functions That Do One Thing

The single most effective change you can make to any codebase is to shorten its functions. A function that does one thing has a name you can guess, arguments you can understand, and a body you can hold in your head.

How to tell a function is doing too much

• You need the word and to describe what it does.
• It has more than about three parameters.
• It needs a comment to explain its sections.
• Parts of it could be reused somewhere else, but cannot be because they are buried inside.
• You cannot test one behaviour without setting up all the others.

Before and after

Extract until it is obvious

The test for a well-extracted function is that reading its body tells you what it does without any further explanation. If you can read the function aloud as a sentence, the extraction was right.

// Reads like a sentence:
// "An order is valid if it has items and a customer"
function isValidOrder(order) {
    return Boolean(order?.items?.length && order?.customer);
}

// "An item subtotal is price times quantity"
function itemSubtotal(item) {
    return item.price * item.quantity;
}

// "The order subtotal is the sum of every item subtotal"
function orderSubtotal(items) {
    return items.reduce((sum, item) => sum + itemSubtotal(item), 0);
}

// "A total is the subtotal plus tax"
function applyTax(subtotal, rate) {
    return subtotal * (1 + rate);
}

// And then the top-level function just reads well:
function calculateOrderTotal(order) {
    if (!isValidOrder(order)) return 0;
    return applyTax(orderSubtotal(order.items), TAX_RATE);
}

Names That Say What They Mean

A name is the smallest piece of documentation in a program. The conventions are covered in JavaScript Naming Conventions; this section is about the choice of which name, not the casing.

Name by meaning, not by type or content

Verbs for functions, nouns for values

// A function name should describe the action
function calculateTotal(items) { }
function fetchUser(id) { }
function renderCard(data) { }
function isValidEmail(value) { }
function formatPrice(cents) { }

// A variable name should describe the value
const currentUser = fetchUser(id);
const cartTotal = calculateTotal(items);
const emailIsValid = isValidEmail(input);

// Nouns as function names are a smell —
// they usually mean the function is doing
// too much or the name is not specific
function user(id) { }        // what about the user?
function total(items) { }    // total what?

// Booleans should read as a question
const isLoading = true;
const hasPermission = false;
const canEdit = true;
const shouldRetry = false;

Avoid catch-all names

data, info, temp, result, and item are placeholders masquerading as names. They tell you nothing and they make every line that uses them harder to read.

// Vague — the reader has to look elsewhere
function process(data) {
    const info = data.details;
    const temp = info.value * 2;
    const result = temp + 10;
    return result;
}

// Specific — the names carry the meaning
function calculateDiscountedPrice(product) {
    const discountDetails = product.discount;
    const doubledDiscount = discountDetails.value * 2;
    const finalPrice = doubledDiscount + BASE_FEE;
    return finalPrice;
}

Fewer Side Effects, Clearer Code

A pure function reads only its arguments and returns a value. It does not modify anything outside itself, does not log, does not fetch, and does not set a global. It is the easiest kind of code to test, reuse, and reason about.

The same function with a side effect is harder to trust. It looks the same at the call site, but it does something extra.

Mutating a local variable is fine

Purism about mutation misses the point. A local accumulator inside a function is completely fine. The problem is mutating something shared — a parameter, a module-level object, or a value owned by another part of the program.

Watch for accidental mutation through references

// This looks harmless but mutates the original
function addItem(cart, item) {
    cart.items.push(item);   // mutates the caller's array
    return cart;
}

// Two fixes, depending on intent

// 1. Return a new object (preferred for shared state)
function addItemImmutable(cart, item) {
    return {
        ...cart,
        items: [...cart.items, item]
    };
}

// 2. Or make the mutation explicit in the name
function addItemInPlace(cart, item) {
    cart.items.push(item);
    return cart;
}

// The second is fine if the mutating
// behaviour is the point — the name
// tells the caller what to expect.

Control Flow: Early Return and Fewer Branches

Deeply nested code is hard to read because you have to hold every surrounding condition in your head while you read the innermost line. Early return flattens that.

Prefer a lookup table to a long if/else chain

// Instead of a chain of conditions
function getStatusLabel(status) {
    if (status === 'pending') return 'Waiting';
    if (status === 'shipped') return 'On the way';
    if (status === 'delivered') return 'Arrived';
    if (status === 'cancelled') return 'Cancelled';
    return 'Unknown';
}

// Use a map
const STATUS_LABELS = {
    pending: 'Waiting',
    shipped: 'On the way',
    delivered: 'Arrived',
    cancelled: 'Cancelled'
};

function getStatusLabel(status) {
    return STATUS_LABELS[status] ?? 'Unknown';
}

// Adding a status is one line
// in the map, not a new branch.

Avoid flag arguments

A boolean parameter that switches what a function does is a sign the function has two behaviours. Split it into two functions with names that describe each case.

Error Handling That Actually Helps

Errors are information. Handling them well means the reader can tell what can go wrong, what happened when it did, and what the program is going to do about it.

Throw for exceptional cases, catch only what you can handle

Write meaningful error messages

// Useless — says nothing about what happened
throw new Error('Error');

// Better — says what went wrong
throw new Error('Invalid JSON input');

// Best — says what went wrong and where
function parseUser(json) {
    try {
        return JSON.parse(json);
    } catch (error) {
        throw new Error(
            `Failed to parse user JSON: ${error.message}`,
            { cause: error }
        );
    }
}

// Custom error classes let callers handle
// specific failure types
class ValidationError extends Error {
    constructor(field, message) {
        super(message);
        this.name = 'ValidationError';
        this.field = field;
    }
}

// And callers can distinguish them
try {
    createUser(input);
} catch (error) {
    if (error instanceof ValidationError) {
        highlightField(error.field);
    } else {
        throw error;
    }
}

Do not use errors for control flow

Clean Asynchronous Code

Asynchronous code has one main trap: doing things in sequence that could happen in parallel, and doing them in a way that makes error handling hard to follow. Both have simple fixes.

Prefer async/await to long promise chains

Run independent requests in parallel

Two awaits in sequence take the sum of both durations. Promise.all takes the longer of the two.

Do not await inside a loop when you do not have to

// Sequential — each iteration waits for the one before
async function fetchAllUsers(ids) {
    const users = [];
    for (const id of ids) {
        users.push(await fetchUser(id));   // slow
    }
    return users;
}

// Parallel — all requests fire at once
async function fetchAllUsers(ids) {
    return Promise.all(ids.map(id => fetchUser(id)));
}

// If the loop genuinely must be sequential
// — for example, because each request depends
// on the previous response — keep the await
// inside, but say so in a comment.

Structure and Organization

Clean code is not only about individual functions. It is also about where things live and how the pieces relate to each other.

One responsibility per file

• A file should have one reason to change. If the user model and the user API client live together, they will change for unrelated reasons.
• Group by feature, not by type. A checkout/ folder holding the component, the API call, and the types is easier to navigate than three folders that each hold one piece.
• Keep the public surface small. Export what other modules need, and keep the rest internal.
• Name files after what they export. userService.js exports a user service.

Keep related code together

Module boundaries

// userService.js — one responsibility

const API_URL = '/api/users';

async function findById(id) {
    const response = await fetch(`${API_URL}/${id}`);
    if (!response.ok) throw new Error(`User ${id} not found`);
    return response.json();
}

async function create(data) {
    const response = await fetch(API_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
    });
    if (!response.ok) throw new Error('Could not create user');
    return response.json();
}

export { findById, create };

// The module exposes two named
// functions and nothing else.
// Everything else is internal.

A Full Refactor, Step by Step

The best way to see what clean code looks like is to take a messy function and clean it up. Here is one, with each step explained.

The original

function p(d) {
    if (d && d.u && d.i && d.i.length > 0) {
        let t = 0;
        for (let i = 0; i < d.i.length; i++) {
            const x = d.i[i];
            if (x.q > 0) {
                t = t + x.pr * x.q;
            }
        }
        t = t * 1.2;
        d.t = t;
        save(d);
        return d;
    } else {
        return null;
    }
}

// What is `d`? What is `p`?
// What is `t`, `i`, `x`, `q`, `pr`?
// The reader has to open the
// implementation and work it out.

The refactor, step by step

After the refactor

const TAX_RATE = 0.2;   // 20% VAT, fixed by legislation

function itemSubtotal(item) {
    return item.price * item.quantity;
}

function calculateSubtotal(items) {
    return items
        .filter(item => item.quantity > 0)
        .reduce((sum, item) => sum + itemSubtotal(item), 0);
}

function calculateTotal(subtotal, rate = TAX_RATE) {
    return subtotal * (1 + rate);
}

async function processOrder(order) {
    if (!order?.items?.length) {
        return null;
    }

    const subtotal = calculateSubtotal(order.items);

    const processed = {
        ...order,
        total: calculateTotal(subtotal),
        status: 'processed'
    };

    await save(processed);

    return processed;
}

// Every name says what it holds.
// Every function does one thing.
// The caller's order is untouched.
// Each piece is testable in isolation.

What the refactor changed

Tooling That Keeps It Clean

A convention that lives only in a document drifts. A convention enforced by a tool holds. The setup takes an afternoon and pays back forever.

Prettier for formatting

Prettier removes every argument about whitespace, quotes, and line breaks. It formats on save, so nobody has to think about it.

// .prettierrc

{
    "semi": true,
    "singleQuote": true,
    "tabWidth": 4,
    "trailingComma": "es5",
    "printWidth": 90,
    "arrowParens": "avoid"
}

// Any of these choices is fine. The point is
// that everyone on the team uses the same one.

ESLint for correctness

// eslint.config.js — the rules that catch real mistakes

export default [
    {
        rules: {
            // Variables
            'no-unused-vars': 'error',
            'no-shadow': 'error',
            'no-redeclare': 'error',
            'prefer-const': 'error',

            // Functions
            'no-param-reassign': 'error',
            'max-params': ['warn', 4],
            'max-depth': ['warn', 4],
            'max-lines-per-function': ['warn', 60],

            // Async
            'no-async-promise-executor': 'error',
            'require-await': 'warn',

            // Comparison and equality
            eqeqeq: ['error', 'always'],
            'no-implicit-coercion': 'warn',

            // Errors
            'no-empty': ['error', { allowEmptyCatch: false }]
        }
    }
];

What each rule buys you

Run it in CI

// package.json

{
    "scripts": {
        "lint":       "eslint .",
        "format":     "prettier --write .",
        "format:check": "prettier --check .",
        "test":       "vitest run",
        "ci":         "npm run format:check && npm run lint && npm run test"
    }
}

// A linter that only runs when someone
// remembers is a linter that does not run.
// Add it to the pipeline.

Anti-Patterns to Avoid

These are the patterns that look reasonable in isolation and become problems as a codebase grows. Recognizing them early saves a lot of rework.

1. The god function

A single function that handles validation, business logic, persistence, and side effects. Split it into named pieces — each one testable on its own.

2. Boolean trap parameters

3. Magic numbers and strings

4. Comments that explain the code instead of the reason

5. Deeply nested callbacks and promise chains

Use async/await with try/catch. It reads sequentially and keeps errors in one place.

6. Mixing mutation and return values

7. Catch-all try blocks

A try block wrapping fifty lines hides which line actually failed. Keep try blocks small and specific.

8. Global mutable state

A Practical Checklist

Before you consider a function finished, run through this list. Most items take seconds to check and save minutes later.

• Can the function name be read aloud as a sentence describing what it does?
• Does it do one thing — no and in the description?
• Are all names meaningful, with no data, temp, or single letters outside a tiny scope?
• Are booleans prefixed with is, has, can, or should?
• Does the function avoid mutating its parameters?
• Are the exceptional cases handled first, with the happy path at the top level?
• Is every catch block either handling the error or re-throwing it?
• Are independent async operations run in parallel with Promise.all?
• Are magic numbers and strings named as constants?
• Do comments explain the why, not the what?
• Does the file have one reason to change?
• Does the whole thing pass the linter and the formatter without complaints?

Key Takeaways

• Clean code is about making the next change easy — not about style for its own sake.
• A function should do one thing; if you need and to describe it, split it.
• Name by meaning, not by type or content. Booleans read as a question.
• Prefer pure functions — read the inputs, return a result, change nothing outside.
• Mutating a local variable is fine; mutating a shared one is where bugs live.
• Use early returns so the happy path stays at the top level.
• Replace long condition chains with a lookup table.
• Avoid boolean flag parameters — split into two named functions.
• Catch only what you can handle, and never leave an empty catch block.
• Prefer async/await to long promise chains.
• Run independent async operations in parallel with Promise.all.
• Use Prettier for formatting and ESLint for correctness, and run both in CI.

What to Learn Next

Now that the habits are clear, the next step is the language details they rest on. Read JavaScript Naming Conventions for the casing rules, and JavaScript Comments for the documentation side.

From there, explore JavaScript Functions Explained, JavaScript Array Methods, and JavaScript Statements and Expressions. For the async side, read Async and Await Explained and How JavaScript Works.

If you are still connecting the pieces, read What Is JavaScript?, JavaScript Strict Mode, and JavaScript vs TypeScript for the surrounding context.

Practice Challenge

The fastest way to learn clean code is to clean up something dirty. This exercise takes about thirty minutes.

1. Create index.html and app.js, and load the script with <script src="app.js" defer></script>.
2. Write a deliberately messy function: a one-letter name, a single-letter parameter, an inline loop, a magic number, and a try block that catches and ignores errors.
3. Add a global mutable variable that the function reads, such as let currentUser.
4. Have the function both mutate its parameter and return it, so the caller cannot tell which it does.
5. Have the function do three things — validate, transform, and save — all in one body, with the save wrapped in try/catch.
6. Confirm the script runs. Then read it out loud. Note every place you have to stop and work out what a name means.
7. Now refactor step by step. Rename the function to a verb phrase and the parameter to a descriptive noun.
8. Extract the loop into a named function that does one thing.
9. Replace the magic number with a named constant, with a comment explaining where the value comes from.
10. Replace the nested condition with a guard clause at the top.
11. Change the function to return a new object instead of mutating its parameter.
12. Move the save call out of the try/catch and handle the error explicitly — re-throw anything you cannot handle.
13. Remove the global variable and pass the value as a parameter instead.
14. Finally, install Prettier and ESLint. Enable no-unused-vars, no-param-reassign, prefer-const, and eqeqeq. Run both and fix anything they flag.

If you complete those steps, you have written code that breaks nearly every rule in this guide, refactored it into something readable, moved a side effect out of a hidden place, and configured the tooling that keeps the rules in place. That last part matters most: the refactor teaches you what clean code looks like, and the linter makes sure the next person writes it that way too.