JavaScript

How to write Comments in JavaScript code

Comments are notes that a programmer leaves in their code to make it more understandable. Most senior devs focus on writing code which is efficient and can be easily read and interpreted by computers. However it is of equal importance to make the code easily readable for the people (who will be working with the code in future) as well. A programmer must know how to properly structure code to make it more understandable for humans.

What are Comments?

Comments can be anything from a single line explanation to multi-line description of code that is written inside the source code of a program. They are usually used to leave notes in the complex parts of the source code so anyone who looks at the code in future can easily understand the purpose of that piece of code. This practice saves time as anyone can easily understand the purpose of code without making any effort.

Now Let’s start learning how to properly structure JavaScript source code by writing different types of comments:

Types of Comments in JavaScript

JavaScript has two main types of comments:

  • Single-line comments.
  • Multi-line comments

Single-line Comments : In JavaScript two forward slashes (//) are used to write single-line comments:

// A single-line Comment

The comments in any programming language have no effect on the actual program. The interpreters/compilers of programming languages are designed in a way that they ignore all the comments when interpreting/compiling a program.

Comments can have their own separate lines; they can also be added inline with other code as well.

Inline Comments : When Single-line comments are used in the same line as code then they are referred to as inline comments:

let a = 30; // an inline comment

let b = a + 10; // adding 10 in "a" variable and assigning it to "b"

The inline comments are used to explain the exact line of code they are written on; they can be used for a specific, small description of the code present at that line.

Multi-line Comments : In JavaScript the block comments the multi-line comments are written in the same way as they are written in CSS with opening tags (/*) and closing tags (*/):

/* A Block

Comment*/

All the text between the opening and closing tags is ignored by the interpreters.

Multi-line comments or Block-level comments are used to explain and give detailed description of a section of code. This type of comments are usually placed at the top of the source code file or before a particularly complex code block:

/* Fetching the name of the user

from an Input field

and showing it on the console */


function showUser() {

const name = document.getElementById('user-name');

console.log("Hello and welcome to the Linuxhint.com," + name + ".");

}

showUser();

Commenting Out Code for Testing/Debugging : Comments can be used to quickly and easily prevent the execution of a block code; so many senior JavaScript devs also use comments for testing and debugging purposes. Placing the comment tags behind a block of code so it is ignored by the interpreter and does not get executed is referred to as “commenting out code”.

Commenting out code helps in pinpointing the cause of an error in code. They can also be used to test different blocks of code to get different results:

// Function for dividing two numbers

function division(dividend, divisor) {

let quotient = dividend / divisor;

return quotient;

}

// Function for subtracting two numbers

function subtraction(num1, num2) {

let sub = num1 - num2;

return sub;

}

/* In the following line of code, we are commenting out the function call of the division function. Therefore, only the subtraction() function will be called and executed. */

// division(30, 5);

multiplyTwoNumbers(9, 3);

Practices for writing good JavaScript code

Here we will discuss the three best practices for writing good JavaScript code:

Comments are generally written above the block of code they are explaining:

// Show "Hello, Linuxhint!" on the console

console.log("Hello, Linuxhint!");</td>

Indent comments at the same level as the code immediately below them:

// function definition

function showUser() {

// fetching the user-name

const name = document.getElementById('user-name');

// print the message on the console

console.log("Hello and welcome to the Linuxhint.com," + name + ".");

}

Remember there is no way to end the inline comments; so they should be written only after the code for that line has been written completely:

for (let i = 0; i === 10; i++) // for loop that runs ten times {

// Running this code results in a syntax error

}

Conclusion

How many times have you solved a complex problem by writing some code only to come back a few months later and find out that you remember and understand nothing? Comments help you avoid that by writing detailed explanations/descriptions of your code. They also help in debugging testing and pinpointing the source of errors in your code. Both single and multiline comments can be used for debugging/testing purposes. If you are a beginner JavaScript dev, you should write as many comments as possible in your code as they are necessary to comprehend the code you write; but do remember that they should only be added where they are needed.

About the author

Shehroz Azam

A Javascript Developer & Linux enthusiast with 4 years of industrial experience and proven know-how to combine creative and usability viewpoints resulting in world-class web applications. I have experience working with Vue, React & Node.js & currently working on article writing and video creation.