A Guide to Writing Clean, Readable, and Maintainable Code in JavaScript

Author: neptune | 23rd-Feb-2024
#JavaScript

Software development is an evolving craft, and writing clean, readable, and maintainable code is a crucial aspect of being a proficient developer. This guide draws inspiration from Robert C. Martin's Clean Code principles and focuses on adapting them for JavaScript. It's not a strict style guide but rather a set of guidelines to produce code that is not only functional but also easy to understand and maintain.

The Significance of Clean Code


The principles outlined in this guide are not mandates; they are distilled from years of collective experience by the authors of Clean Code. While not every principle must be strictly followed, they provide a touchstone to assess the quality of JavaScript code. In an industry where our understanding is still evolving, these guidelines serve as a foundation for writing code that stands the test of time.


The Journey of Software Engineering


The field of software engineering is relatively young, just over 50 years old. As we continue to learn and evolve, these guidelines act as a compass to navigate the complexities of code. Unlike other disciplines like architecture, which has centuries of established principles, software engineering is still in its formative years. Embracing these guidelines helps shape code into a refined form, acknowledging that every piece of code starts as a draft and matures through iterative refinement.


Variables Matter

Use Meaningful and Pronounceable Variable Names

In the quest for brevity, developers might be tempted to use cryptic variable names. However, clarity should not be sacrificed for conciseness. For instance:


Bad code Example:


    const yyyymmdstr = moment().format("YYYY/MM/DD");



Good code Example:


    const currentDate = moment().format("YYYY/MM/DD");



Use the Same Vocabulary for the Same Type of Variable

Consistency in naming conventions enhances code readability and comprehension. It simplifies understanding, as demonstrated below:


Bad code Example:


    getUserInfo();

    getClientData();

    getCustomerRecord();



Good code Example:


    getUser();



Use Searchable Names

Given that developers read more code than they write, making code searchable is paramount. Meaningful variable names aid in understanding, and tools like buddy.js and ESLint can help identify unnamed constants:


Bad code Example:


    setTimeout(blastOff, 86400000);



Good code Example:


    const MILLISECONDS_PER_DAY = 60 * 60 * 24 * 1000; //86400000;

    setTimeout(blastOff, MILLISECONDS_PER_DAY);



Use Explanatory Variables

Clear and descriptive variable names enhance code readability and comprehension. This helps in understanding the purpose of the variables without delving into the details of their implementation. 

Consider the following examples:

Bad code Example:


    const address = "One Infinite Loop, Cupertino 95014";

    const cityZipCodeRegex = /^[^,\\]+[,\\\s]+(.+?)\s*(\d{5})?$/;

    saveCityZipCode(

    address.match(cityZipCodeRegex)[1],

    address.match(cityZipCodeRegex)[2]

    );




Good code Example:


    const address = "One Infinite Loop, Cupertino 95014";

    const cityZipCodeRegex = /^[^,\\]+[,\\\s]+(.+?)\s*(\d{5})?$/;

    const [_, city, zipCode] = address.match(cityZipCodeRegex) || [];

    saveCityZipCode(city, zipCode);



By introducing explanatory variables (`city` and `zipCode`), the code becomes more self-documenting, making it easier for others to understand the intent.


Avoid Mental Mapping

Code should be explicit and not require developers to mentally map variables to their meanings. In other words, make the code speak for itself. Consider the following:


Bad code Example:

    const locations = ["Austin", "New York", "San Francisco"];

    locations.forEach(l => {

        doStuff();

        doSomeOtherStuff();

        // ...

        // ...

        // ...

        // Wait, what is `l` for again?

        dispatch(l);

    });




Good code Example:

    const locations = ["Austin", "New York", "San Francisco"];

    locations.forEach(location => {

        doStuff();

        doSomeOtherStuff();

        // ...

        // ...

        // ...

        dispatch(location);

    });




By using a more explicit variable name (`location`), the code eliminates the need for mental mapping, making it easier to understand at a glance.


Don't Add Unneeded Context

Avoid redundant information in variable names, especially when the context is already clear from the surrounding code. This principle prevents unnecessary verbosity and redundancy:


Bad code Example:

    const Car = {

        carMake: "Honda",

        carModel: "Accord",

        carColor: "Blue"

    };


    function paintCar(car, color) {

        car.carColor = color;

    }




Good code Example:

    const Car = {

        make: "Honda",

        model: "Accord",

        color: "Blue"

    };


    function paintCar(car, color) {

        car.color = color;

    }



In the good example, the variable names are concise, providing information without repeating what is already evident from the context.


Enhancing Function Clarity: Default Parameters in JavaScript

Use Default Parameters Instead of Short Circuiting or Conditionals


One way to improve the clarity and conciseness of your JavaScript functions is by leveraging default parameters. This approach is often preferable to short circuiting or using conditionals to assign default values. However, it's essential to be aware of the limitations of default parameters.


Bad code Example:

    function createMicrobrewery(name) {

        const breweryName = name || "Hipster Brew Co.";

        // ...

    }




Good code Example:

    function createMicrobrewery(name = "Hipster Brew Co.") {

        // ...

    }



The good example showcases the use of default parameters, making the code more succinct and eliminating the need for a conditional assignment. The function now provides a default value for the `name` parameter without resorting to short circuiting.


Understanding Default Parameter Behavior


It's crucial to note that default parameters replace only `undefined` values. Other "falsy" values such as `''`, `""`, `false`, `null`, `0`, and `NaN` will not be replaced by the default value. This behaviour ensures that default values are assigned only when the parameter is explicitly `undefined`.


By embracing default parameters, you not only enhance the readability of your functions but also reduce the need for additional conditional checks, resulting in cleaner and more maintainable code. This practice aligns with the broader goal of producing clean, readable, and maintainable JavaScript code, as advocated by software engineering principles like those found in Robert C. Martin's Clean Code.


Conclusion

By incorporating these principles into your coding practices, you contribute to creating code that is not only functional but also maintainable and easily understandable by your peers. Clean code is an ongoing effort, and adherence to these guidelines will result in a more enjoyable and collaborative development experience.

So, focus on improving the code, not just for yourself but for the entire development team.





Related Blogs
Generate Fibonacci Sequence - JavaScript | Hackerank
Author: neptune | 07th-Apr-2023
#JavaScript #Hackerrank
Write a JavaScript function fibonacciSequence() to generate a FIbonacci sequence...

To Be Or Not To Be | #2704 | LeetCode Solution
Author: neptune | 03rd-Sep-2023
#JavaScript #LeetCode
Write a function that helps developers test their code. It should take in any value and return an object with the following two functions...

Apply Transform Over Each Element in Array | #2635 | LeetCode Solution
Author: neptune | 05th-Sep-2023
#JavaScript #LeetCode
Given an integer array `arr` and a mapping function `fn`, return a new array with a transformation applied to each element...

Function Composition | #2629 | LeetCode Solution
Author: neptune | 09th-Sep-2023
#JavaScript #LeetCode
Given an array of functions [f1, f2, f3, ..., fn], return a new function fn that is the function composition of the array of functions...

Counter | #2620 | LeetCode Solution
Author: neptune | 02nd-Sep-2023
#JavaScript #LeetCode
Given an integer n, return a counter function. This counter function returns n and then n + 1, n + 2, etc...

Counter 2 | #2665 | LeetCode Solution
Author: neptune | 04th-Sep-2023
#JavaScript #LeetCode
Write function 'createCounter' It accept an initial integer 'init' It should return an object with three functions- increment() , decrement(), reset()...

Chunk Array | #2677 | LeetCode Solution
Author: neptune | 19th-Sep-2023
#JavaScript #LeetCode
Given an array arr and a chunk `size`, return a `chunked` array...

Array Reduce Transformation | #2626 | LeetCode Solution
Author: neptune | 09th-Sep-2023
#JavaScript #LeetCode
Given an integer array `nums` and a reducer function `fn`, and an initial value `init`, return a reduced array...

Add Two Promises | #2723 | LeetCode Solution
Author: neptune | 12th-Sep-2023
#JavaScript #LeetCode
Given two promises `promise1` and `promise2`, return a new `promise`. `promise1` and `promise2` will both resolve with a number...

Managing Virtual Environments in React JavaScript Projects
Author: neptune | 28th-Jun-2023
#JavaScript #React.js
Virtual environments are a valuable tool in React JavaScript projects as they allow developers to isolate dependencies, manage package versions, and maintain project consistency...

Arrow Functions in JavaScript | ES6
Author: neptune | 26th-Mar-2023
#JavaScript #React.js
In this article, we will explore the syntax and usage of arrow functions in detail, along with some examples...

Different ways to handle state in React applications
Author: neptune | 21st-Jun-2023
#JavaScript #React.js
This article explores different ways to manage states in React, including local component state, context API, and state management libraries like Redux...

Filter Elements from Array | #2634 | LeetCode Solution
Author: neptune | 06th-Sep-2023
#JavaScript #LeetCode
Given an integer array `arr` and a filtering function `fn`, return a filtered array `filteredArr`...

Is Object Empty | #2727 | LeetCode | JavaScript Solution
Author: neptune | 01st-Sep-2023
#JavaScript #LeetCode
Given an object or an array, return if it is empty...

From REST to GraphQL: The Future of API Design
Author: neptune | 25th-Feb-2024
#JavaScript
Unlike traditional REST APIs, GraphQL provides a more flexible and intuitive approach to data querying and retrieval...

How I Built My Blogging Website Using React, Node.js, and Jamstack Architecture?
Author: neptune | 31st-Jul-2024
#JavaScript #API
Building a blogging website using React, Node.js, and Jamstack architecture was a rewarding experience...

How to Perform Unit Testing in React Components with Examples?
Author: neptune | 25th-Jul-2024
#JavaScript #React.js
Unit testing in React is an essential practice to ensure the reliability and robustness of your components...

Do you know ! How to manage State in Functional & Class Components in React ?
Author: neptune | 25th-Jul-2024
#JavaScript #React.js
State management in React has evolved significantly with the introduction of Hooks...

Why, What, and When: Understanding Jamstack?
Author: neptune | 05th-Jul-2024
#JavaScript #API
Jamstack represents a modern approach to web development that addresses many of the challenges faced by traditional architectures...

How to Get Started with Jamstack: A Comprehensive Guide?
Author: neptune | 05th-Jul-2024
#JavaScript #API
Getting started with Jamstack involves choosing the right tools, setting up a structured development environment...

View More