DEV Community

Cover image for Comments and Code Refactor
Bello Osagie
Bello Osagie

Posted on • Updated on

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.

Top comments (1)

Collapse
 
abrahamlawson profile image
Lawson

tks