Forem

Cover image for Comments and Code Refactor
Bello Osagie
Bello Osagie

Posted on • Edited on

4 2

Comments and Code Refactor


Comments

There are two types of comments in JavaScript:

  • Inline comments (//...) - inline to statements, expressions, etc
  • Multi-line comments (/*...*/) - span multiple lines;

Comments are notes describing how and why the code works. It is crucial as a reminder to the creator of the code and when working with other developers.

If the code has anything subtle and counter-intuitive, it's definitely worth commenting.

There are times when novices use them wrongly.

Bad Comments

Many comments are bad practices. The example shows the logic of creating a prime number in JavaScript in bad comments.

See the example below:

function showPrimes(n) {
  // nextPrime is just a label
  nextPrime:
  for (let i = 2; i < n; i++) {
    /* 
    The iteration starts at 2 through to n - 1. For example, if n is 
    10, iteration starts from iteration 2 to iteration 9. 9 is 
    less than 10    
    */

    for (let j = 2; j < i; j++) {
      // iteration from j = 2 to j < i in all j complete circles

      if (i % j === 0) continue nextPrime;
      /* if iteration of i and j modulus equals zero then it's not 
      a prime number */
    }

    console.log(i); // 2, 3, ...7
  }
}

showPrimes(10)
Enter fullscreen mode Exit fullscreen mode

Good Comments

Comments should be logical (when necessary) but short.

See the example below:

const showPrimes = (n) => {
    nextPrime:
    for (let i = 2; i < n; i++) {
        // 2, 3, 4, 5, 6, 7, 8, 9

        for (let j = 2; j < i; j++) {
            // j2 = 2, 
            // j3 = (2, 3), 
            // j4 = (2, 3, 4), 
            // j5 = (2, 3, 4, 5), 
            // j6 = (2, 3, 4, 5 ,6), 
            // j7 = (2, 3, 4, 5 ,6, 7), 
            // j8 = (2, 3, 4, 5, 6, 7, 8)

            // i2
            // i3 : j2
            // i4 : j2, j3
            // i5 : j2, j3, j4
            // i6 : j2, j3, j4, j5
            // i7 : j2, j3, j4, j5, j6
            // i8 : j2, j3, j4, j5, j6, j7 
            // i9 : j2, j3, j4, j5, j6, j7, j8

            if (i % j === 0) continue nextPrime;
            // i2 => 2, 
            // i3 : j2 => (3 / 2) (3), 
            // i5 : j2, j3, j4 => ( 5 / (2, 3, 4) ) (5), 
            // i7 : j2, j3, j4, j5, j6 => ( 7 / (2, 3, 4, 5, 6) ) (7)
        }

        console.log(i); // 2, 3, 5, 7
    }
};

showPrimes(10);
Enter fullscreen mode Exit fullscreen mode

The comment above looks logical but overused.



See the example below of reduced comments:

function showPrimes(n) {
  nextPrime:
  for (let i = 2; i < n; i++) {
    // i = i2, ...i(n-1)

    for (let j = 2; j < i; j++) {
      // in = j1, ...j(n-2)

      if (i % j === 0) continue nextPrime;
      // !R(i/j)
    }

    console.log(i); 
  }
}

showPrimes(10);
Enter fullscreen mode Exit fullscreen mode

Not only the comment above is short, but also precise.

Good comments contain the following:

  • Describe the architecture
  • Document function parameters and usage
/**
 * Returns x raised to the n-th power.
 *
 * @param {number} x The number to raise.
 * @param {number} n The power, must be a natural number.
 * @return {number} x raised to the n-th power.
 */

function pow(x, n) {
  // ...
}
Enter fullscreen mode Exit fullscreen mode
  • such comments above make the function understandable without looking in its code

  • some editors like WebStorm understand comments to provide autocomplete and some automatic code-checking to ease workflow

  • tools like JSDoc 3 that can generate HTML-documentation from the comments. The official documentation is at usejsdoc.org/

Most of the time comments are used in development only but removed in production especially when minified.

Code refactor

Code refactoring is the process of modifying the code structure without affecting the functionality for readability purposes.

See the example below:

function showPrimes(n) {
  nextPrime:
  for (let i = 2; i < n; i++) {

    for (let j = 2; j < i; j++) {

      if (i % j === 0) continue nextPrime;
    }

    console.log(i); 
  }
}

showPrimes(10);
Enter fullscreen mode Exit fullscreen mode

To refactor or make the code more readable above see the example below:

function showPrimes(n) {

  for (let i = 2; i < n; i++) {
    if (!isPrime(i)) continue;

    console.log(i);
  }
}

function isPrime(n) {
  for (let i = 2; i < n; i++) {
    if (n % i == 0) return false;
  }

  return true;
}

showPrimes(10);
Enter fullscreen mode Exit fullscreen mode

The code above looks easier to understand because it has lesser nesting and better factored out function isPrime.

The function itself becomes the comment. Such code is called self-descriptive.

Refactoring split code structure to make functions more understand.

Happy coding!


Buy me a Coffee


TechStack Media | Domain

  • Purchase a .com domain name as low as $9.99.
  • Purchase a .net domain name as low as $12.99.
  • Get cheaper domain names as low as $3.
  • Build a website with ease.

Image of Timescale

🚀 pgai Vectorizer: SQLAlchemy and LiteLLM Make Vector Search Simple

We built pgai Vectorizer to simplify embedding management for AI applications—without needing a separate database or complex infrastructure. Since launch, developers have created over 3,000 vectorizers on Timescale Cloud, with many more self-hosted.

Read full post →

Top comments (1)

Collapse
 
abrahamlawson profile image
Lawson

tks

Cloudinary image

Optimize, customize, deliver, manage and analyze your images.

Remove background in all your web images at the same time, use outpainting to expand images with matching content, remove objects via open-set object detection and fill, recolor, crop, resize... Discover these and hundreds more ways to manage your web images and videos on a scale.

Learn more

👋 Kindness is contagious

Engage with a sea of insights in this enlightening article, highly esteemed within the encouraging DEV Community. Programmers of every skill level are invited to participate and enrich our shared knowledge.

A simple "thank you" can uplift someone's spirits. Express your appreciation in the comments section!

On DEV, sharing knowledge smooths our journey and strengthens our community bonds. Found this useful? A brief thank you to the author can mean a lot.

Okay