Comments and Code Refactor
Tags: javascript, tutorial, codenewbie, webdev
Published: 2021-02-03 22:35:22

{% youtube v3oCoYM0RCs %}

---

### 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:

```js
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:

```js
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.

{% youtube hbnzEmvZJiA %}

---
<a href="https://www.whogohost.com/host/aff.php?aff=7390&page=hosting" target="_blank"><img src="https://www.whogohost.com/images/affiliates/unlimited-hosting-728-x-90.png" /></a>

---

See the example below of reduced comments:

```js
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 

```js
/**
 * 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](https://www.jetbrains.com/webstorm/) understand comments to provide autocomplete and some automatic code-checking to ease workflow

- tools like [JSDoc](https://github.com/jsdoc3/jsdoc) 3 that can generate HTML-documentation from the comments. The official documentation is at [usejsdoc.org/](https://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:

```js
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:

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

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](https://res.cloudinary.com/bizstak/image/upload/v1610317510/ko-fi-trans_fr3su4.png)](https://www.buymeacoffee.com/techstackmedia)

---

### 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.

<a href="https://domain.mno8.net/c/2653712/848391/9560" target="_top" id="848391"><img src="//a.impactradius-go.com/display-ad/9560-848391" border="0" alt="" width="300" height="250"/></a><img height="0" width="0" src="https://imp.pxf.io/i/2653712/848391/9560" style="position:absolute;visibility:hidden;" border="0" />