Clarifying Code with Javascript Comments

Javascript is built for simplicity and ease of use, but it’s still possible to create complex code that isn’t easy to understand at a glance. For these situations, the Javascript standard provides two ways to create code comments where developers can explain in plain language what is happening.

Although a browser doesn’t execute Javascript comments, including comments is an important best practice in software development. Nearly all Javascript code can benefit from the addition of comments to explain how it works; adding useful comments is a sign of good code quality.

This article covers how to create Javascript comments, how they’re used within a program, and some best practices for creating the most effective comments possible.

Writing Javascript Comments

There are two different ways to write comments in Javascript: on a single line or on multiple lines. The syntax for each comment type is slightly different, but there can be some overlap between them stylistically if a developer prefers.

Single Line Comments

Single line Javascript comments start with two forward slashes (//). All text after the two forward slashes until the end of a line makes up a comment, even when there are forward slashes in the commented text.

// This is a single line comment.
x = 5;  // This is a single line comment as well!
// This is a single line comment containing a URL: http://example.com

A group of single line comments makes more extensive commenting possible, and Javascript also supports multiline (block) comments, as shown in the next section.

// This is an example of single line comments
// emulating multiline comments.
// After three lines or so, block comments
// are usually easier to maintain.

Multiline (Block) Comments

Javascript multiline comments, also known as block comments, start with a forward slash followed by an asterisk (/*) and end with an asterisk followed by a forward slash (*/). They do not require a comment delimiter character on every line and may contain newlines.

/*
This is a multiline comment
that can span as many lines
as you have the patience to
compose for your future self.
*/

Multiline comments, also known as comment blocks, are helpful when documenting complex logical flows within if else statements, error handling in try catch statements, and complex properties and behaviors in Javascript objects.

/*
The following tests whether a variable has a value of 1, 2, or 3, then
does something different depending on each value.
A useful if statement in production code would have more detailed
instructions, and this comment would be more detailed as well.
*/
if (x == 1) { ... instructions ... }
else if (x == 2) { ... instructions ... }
else if (x == 3) { ... instructions ... }

Using Javascript Comments to Prevent Code Execution

Since Javascript comments are not executed, they’re a good way to prevent code execution while testing new features. This strategy allows you to locate bugs, progressively removing comments until you find the problematic code.

Commenting Out Function Calls

When creating a new function, it’s often helpful to make sure that the function doesn’t impact any other code negatively or unexpectedly. A common testing strategy is to comment out the new function, then make sure the rest of a program still runs as expected without it.

This example comments out a call to a newly implemented method to make sure it hasn’t affected the rest of the program before testing the method itself. Despite the function for changing the value of “X” existing in the code, the commented out method call prevents the function’s execution.

function doSomething(x) {
    let val = x / 2;
    return val;
}

let x = 1;
let y = 4;
// x = doSomething(y);  // call is commented out, "x" doesn't change

Commenting Out Function Bodies — Without Return Values

It isn’t always necessary to comment out an entire function when testing. If a function doesn’t return a value, you can comment out the body of the function using a Javascript multiline comment. In this case, the function itself would be called, but the value of “X” still wouldn’t change because nothing inside the function would execute.

let x = 1;

function doSomething(z) {
/*
    let a = z * z;
    x = a / 2;
*/}

doSomething(12);

Commenting Out Function Bodies — With Return Values

The previous technique won’t work the same way if the function immediately assigns its result to a variable; commenting out the function body makes the function return an undefined value. The undefined value then changes the value of “X”, which could confuse testing.

function doSomething(z) {
/*
    let val = z / 2;
    return val;
*/}

let x = 1;
let y = 4;
x = doSomething(y);  // "X" would be undefined; may not be desirable

Careful commenting allows developers to pinpoint bugs and track how code works, but it’s easy to introduce unexpected behavior without meaning to while commenting, as the previous example shows. Always make sure you account for any ambiguity your comments may create in testing.

Writing Effective Javascript Comments

Finding the right balance between too many comments and too few, or deciding on which style of comments is best for a certain piece of code, is an ongoing debate among developers, one that is unlikely to be resolved anytime soon. Some codebases follow a formal commenting scheme, while others don’t.

Developers have different preferences for when to use single line or multiline comments, but maintaining a consistent strategy when commenting code ensures that comments are clear regardless of the form they take. Some programmers use single line comments for everything, while others use multiline comments everywhere; some programmers only use block comments for formal documentation, while others use them for any long comment that takes up more than a certain number of lines.

The key to effective Javascript comments, no matter what style you use, is to be consistent. As long as your comments are clear and give developers a walkthrough of how your code works, it doesn’t matter exactly what those comments look like.

Conclusion

Javascript comments explain what code does and clarify the decisions behind code design They also prevent execution of code if necessary.

It’s important to use comments well; too few or too many comments will make code harder to understand than if there were no comments at all. Using the right amount of Javascript comments appropriately can help developers use and maintain code for a long time.

Enroll in our Intro to Programming Nanodegree Program today to learn more about Javascript comments and other programming concepts.

Start Learning