1. javascript
  2. /basics
  3. /comments

JavaScript Comments

JavaScript comments are used to add notes or explanations to the code, which are ignored by the interpreter during execution. They can also be used to temporarily disable a specific line of code.

Single-line Comments

Single-line comments start with // and continue until the end of the line. For example:

// This is a single-line comment;

Multi-line Comments

Multi-line comments start with /* and end with */. Everything between the two symbols is ignored by the interpreter. For example:

/*
This is a
multi-line comment
*/

Best Practices

Using comments in JavaScript should clarify the purpose and functionality of the code, especially in complex or non-obvious sections. Comments can also be used to indicate the authorship of the code, and to provide information about the version or last modification date.

It is important to note that too many or unnecessary comments can make the code hard to read and can be an indication of poor code quality.

Good Comment Example

let data = [1, 2, 3, 4, 5];

/**
 * This function squares every element of an array
 * 
 * @param {Array} arr - array to square
 * @return {Array} - squared array
 */
const squareData = (arr) => {
    let squaredData = arr.map(num => num*num);
    return squaredData;
}

let squaredData = squareData(data);
console.log(squaredData); // [1, 4, 9, 16, 25]

Here, the comments clarify the purpose and functionality of the function, especially in non-obvious sections. They indicate the parameters that the function accepts, what it does, and what is the return type.

Bad Comment Example

let data = [1, 2, 3, 4, 5];

// square data
const squareData = (arr) => {
    // return squared data
    return arr.map(num => num*num);
}

// get squared data
let squaredData = squareData(data);
console.log(squaredData);

Instead of commenting every single line, it's better to use meaningful variable and function names that provide useful information instead of stating the obvious.

Using Comments to Disable Code Execution

It's also possible to use JavaScript comments to disable specific lines of code. This can be useful when debugging or troubleshooting code, as it allows you to quickly comment out sections of code without having to remove them entirely.

For example, to disable the following line of code:

console.log("This is a test");

You would change it to:

// console.log("This is a test");

The interpreter will ignore this line of code and it won't execute.

Comments and IDE's

Comments in JavaScript can be read and utilized by integrated development environments (IDEs) and code editors.

/*
 * variable x stores the value for the maximum number of items allowed
 */
let x = 20;

/*
 * square function 
 * @param {number} num - number to square
 * @return {number} the result of num square
 */
const square = (num) => {
    return num * num;
}

The comments associated with the variable x and the function square provide additional context of their purpose and functionality.

For instance, when we use the square function, the IDE can display the information in the comment above the function, indicating the parameters it accepts, the return type, and what it does.

Summary

Comments are an important aspect of writing clear, maintainable JavaScript code. They can be used to provide explanations and context for complex or non-obvious sections of code, as well as to temporarily disable specific lines of code. However, it's important to use comments sparingly and only when necessary and to keep them up to date as the code evolves.