How and When to Write Comments in Javascript

The first concern in programming is usually how the machine reads the code interprets it. Indeed, taking into account the people who will read and work with the code is very important. Whether you should be working with a team or on your own, learning how to comment and structure your code for readers appropriately will be needed.

Comments are annotations in a program's source code that the interpreter ignores and thus do not affect the code's real result. Comments can often be extremely helpful in understanding the purpose of the part of your code.

As a developer, looking deeper into the code written by anyone else that has not been appropriately commented can be annoying, and it is incredibly easy to forget what your code actually intended when you are no longer involved in that project. If you comment your code properly on the right time, it will become a good programming habit, and you will avoid future misunderstandings.

There is a famous cliché that “Good code is self-documenting.” And when you start a new project, you should think about the clarification and documentation of your code, which can be done by comments.

JavaScript comments can be used in two ways: to clarify JavaScript code and to make it more understandable; to prevent execution when testing alternative code.

There are two different types of JavaScript comments:

  • Single-line comments
  • Multi-line comments

Single-line Comments

Two forward slashes (//) are used to write single-line comments: 
// I am a comment.

JavaScript will ignore (will not execute) any text between the slashes and the end of the line.

See this example which uses a single-line comment before each code line:

Example

<!DOCTYPE html>
<html>
  <head>
    <title>Single-line JavaScript Comments</title>
  </head>
  <body>
    <h2 id="myHeading"></h2>
    <p id="myParagraph"></p>
    <script>
      // For heading
      document.getElementById("myHeading").innerHTML = "Single-line JavaScript Comments";
      // For paragraph
      document.getElementById("myParagraph").innerHTML = "I have comments in my JavaScript code!";
    </script>
  </body>
</html>

Single-line comments are considered to be inline comments when they appear at the end of a line of code.

For quick annotation on small, specific snippets of content, inline comments can be used. Since the comment should relate only to the exact line on which it is written, it is the most apparent type of comment.

Example

JavaScript Inline Comments
let a = 55; // assign numerical value to a let b = a + 4; // assign the sum of a + 4 to b // Write b to demo: console.log(b);
Remember that there is no way to end a single line comment on a line, so make sure not to put any code after the // syntax.

Although inline comments may be useful, they should be used carefully. Code covered in an abundance of inline comments will easily become messy, making it hard to read.

Multi-line Comments

Multi-line comments, widely known as block comments, start with /* and end with */. If you know CSS, then you're already familiar with block-level comments.

JavaScript will ignore any text between the /* and */.

/* I am a
multi-line comment */
Both single-line and multi-line comments are written above the code to clarify the code.

See an example that uses a multi-line comment (a comment block) to simplify the code:

Example

<!DOCTYPE html>
<html>
  <head>
    <title>Multi-line JavaScript Comments</title>
  </head>
  <body>
    <h1 id="myHeading"></h1>
    <p id="myParagraph"></p>
    <script>   
          /*
            This is a multi-line comment.
            You can't see this!
            */
      document.getElementById("myHeading").innerHTML = "Multi-line JavaScript Comments";
      document.getElementById("myParagraph").innerHTML = "I have multi-line comments!";
    </script>
  </body>
</html>

Note that it is most common to use single-line comments. Block comments are often used for formal documentation. And they will sometimes include details about the programming file, including the name, version, and the author of the script.

Use Comments to Prevent Execution When Testing Alternative Code

Comments can be used to prevent code execution for testing and debugging reasons easily and quickly. It's called "commenting out the code."

Adding // in front of a code line changes the code lines from an executable line to comment.

When there is an error in a specific code that you have written, commenting on sections will prevent them from running, and it can be useful to identify the source of the problem. To test different results, you can also use it to switch between code.

See an example that uses the // to prevent the execution of one of the code lines:

Example

<!DOCTYPE html>
<html>
  <head>
    <title>Multi-line JavaScript Comments</title>
  </head>
  <body>
    <h2>JavaScript Comments to Prevent Execution </h2>
    <h1 id="myHeading"></h1>
    <p id="myParagraph"></p>
    <script>
      /*
            document.getElementById("myHeading").innerHTML = "Welcome to my website";
            document.getElementById("myParagraph").innerHTML = "This is my hidden paragraph.";
            */
      document.getElementById("myParagraph").innerHTML = "I have a comment-block that is not executed.";
    </script>
  </body>
</html>

Based on the size of the section being toggled, both single-line comments and block comments may be used to comment out the code.

Commenting out code can be useful when working out a project's logic as you determine where bugs are or assess the lines of code which provide the most utility.

Commenting out code should only be done during testing purposes. Do not leave snippets of commented out code in your final script.

The computer interprets the JavaScript code, but other developers will always read it, as well as for yourself in the future.

Don't regret your time to drop regular annotation on complicated sections of code will be an advantage in the future, making it easier for you and your colleagues to understand the purpose of the code you've written.