In programming, our first consideration is usually the machine — how the computer is reading and interpreting the code we write. However, it’s equally important to consider the people who will be reading and working with the code. Whether you’re working with a team or on your own, you will need to learn to properly comment and structure your code for human readers.
Comments are annotations in the source code of a program that are ignored by the interpreter, and therefore have no effect on the actual output of the code. Comments can be immensely helpful in explaining the intent of what your code is or should be doing.
As a developer, it can be frustrating to delve into code written by someone else that was not properly commented, and it’s remarkably easy to forget what your own code meant when you’re no longer immersed in the context of a program. Commenting your code early on will reinforce good programming habits throughout your career to avoid these issues later on.
Let’s take a quick look at the two different types of JavaScript comment syntax.
Single-line comments are written with two forward slashes (//
):
// This is a comment
All characters immediately following the //
syntax until the end of the line will be ignored by JavaScript.
Block comments, sometimes referred to as mutli-line comments, are written with opening tags (/*
) and closing tags (*/
). If you know CSS, then you’re already familiar with block-level comments.
/* This is
a comment */
Everything between the opening and closing tag in the code block above will be ignored.
Both single-line and multi-line comments are written above the code they are designated to explain, as demonstrated in this “Hello, World!” example:
// Print "Hello, World!" to the console
console.log("Hello, World!");
When writing comments, indent them at the same level as the code immediately below them:
// Initialize a function
function alphabetizeOceans() {
// Define oceans variable as a list of strings
const oceans = ["Pacific", "Atlantic", "Indian", "Antarctic", "Arctic"];
// Print alphabetized array to the console
console.log(oceans.sort());
}
Note that comments are just as much a part of the code as the program itself. Outdated comments can be more of a detriment than no comment at all, so remember to maintain and update comments regularly along with everything else.
Single-line comments are referred to as inline comments when they appear at the end of a line of code.
let x = 99; // assign numerical value to x
let y = x + 2; // assign the sum of x + 2 to y
Inline comments can be used for quick annotation on small, specific snippets of content. Since the comment should only relate to the exact line it’s written on, it is the most obvious type of comment.
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, as seen in the example below.
for (let i = 0; i === 10; i++) // for loop that runs ten times {
// Running this code results in a syntax error
}
Though inline comments can be useful, they should be used sparingly — code covered in an abundance of inline comments will quickly become messy and therefore difficult to read.
Block-level comments, or multi-line comments, are long-form annotations used to introduce and explain a section of code. Often these types of comments are placed at the top of a file, or before a particularly complex code block.
/* Initialize and invoke a the greetUser function
to assign user's name to a constant and print out
a greeting. */
function greetUser() {
const name = prompt("What is your name?");
console.log("Hello ," + name + "! How are you?");
}
greetUser();
You may also sometimes see a slightly modified version of the block comment syntax, which starts with /**
and includes asterisks throughout the left side of comment block.
/**
* Initialize constant with an array of strings.
* Loop through each item in the array and print
* it to the console.
*/
const seaCreatures = ["Shark", "Fish", "Octopus"];
for (const seaCreature of seaCreatures) {
console.log(seaCreature);
}
Sometimes this type of comment will also include details about the programming file, including the script’s name, version, and author.
If you are a beginner in JavaScript, you may write as much as necessary to learn and comprehend the code you write. As you progress as a JavaScript developer, you will be looking to answer the intent, or the why behind the code, as opposed to the how or what.
Comments can also be used to quickly and easily prevent execution of code for testing and debugging purposes. This is referred to as “commenting out code”.
If there is an error in some code you’ve written, commenting out sections will prevent them from running, and can be helpful in pinpointing the source of the issue. You may also use it to toggle between code to test different results.
// Function to add two numbers
function addTwoNumbers(x, y) {
let sum = x + y;
return sum;
}
// Function to multiply two numbers
function multiplyTwoNumbers(x, y) {
let product = x * y;
return product;
}
/* In this example, we're commenting out the addTwoNumbers
function, therefore preventing it from executing. Only the
multiplyTwoNumbers function will run */
// addTwoNumbers(3, 5);
multiplyTwoNumbers(5, 9);
Both single-line comments and block comments can be used to comment out code, depending on the size of the section being toggled.
Note: Commenting out code should only be done during testing purposes. Do not leave snippets of commented out code in your final script.
When working out the logic of a program, commenting out code can prove to be helpful as you determine where bugs are or assess the lines of code that offer the most utility.
JavaScript code is interpreted by the computer, but will always be read by other programmers, including your future self. Taking the time to leave proper annotation on complicated sections of code will pay dividends in the future, making it easier for you and collaborators to understand the intent of the code you have written.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
JavaScript is a high-level, object-based, dynamic scripting language popular as a tool for making webpages interactive.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Sign up for Infrastructure as a Newsletter.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.
It should be noted that comments should be only put where they are needed, as they need to be maintained along the code, and become easily out-of-date, and become more confusing than helpful.
Code readable by itself should be preferred over commented code. In many of the examples above the comments are not necessary because the code is self explaining, e.g.:
Here’s an article about that topic, and you’ll find many more on the internet: https://www.freecodecamp.org/news/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83/
Thank you for the article! Basing on our experience in GBKSOFT, it’s pretty useful when the team is working on the project. I assume that comment may come in handy when you have a cross-functional team and work on Node.js so everyone who knows JS can check the code.
You might at least mention that the
/** */
syntax is for jsdoc and point people to the jsdoc docs.This blog is very clear about the content, and this can be useful to read and learn more knowledge from this blog.
Hey, we forgot to mention
/*!
multiline comment blocks!This comment has been deleted