Comments and Code Refactor

#javascript #tutorial #codenewbie #webdev

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)

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);

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);

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) {
  // ...
}

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);

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);