Writing Comments and Readable Code

Introduction

Welcome back to Writing and Running Your First JavaScript Programs! We are now stepping into the second lesson of the course, so we are officially building momentum. In the previous lesson, we wrote our very first console.log lines and watched JavaScript display text and numbers on the screen. Those programs were short and easy to follow at a glance, but real programs grow longer very quickly, and our future selves - or a teammate - will thank us for leaving helpful notes along the way. In this lesson, we will learn how to: Write comments with // to explain what our code does. Use a comment to temporarily switch off a line of code. Keep our programs tidy with blank lines and one instruction per line. Leave ourselves a TODO note marking work still to be done. By the end, we will have a short greeting program that reads almost like a friendly note.

What Is a Comment?

A comment is a line of text inside our program that is meant for people, not for the computer. When JavaScript runs the program, it skips every comment completely, as if the line were not there at all. In JavaScript, a comment starts with two forward slashes, // . Everything from those slashes to the end of the line is a comment. There is no closing mark to remember: the line simply ends, and so does the comment. Comments are how we explain why the code is there. The code itself already says what happens; a good comment says what it is for. There is also a second form for a note that needs more than one line. A block comment starts with /* and ends with */, and JavaScript ignores everything between the two marks, even across several lines: JavaScript /* This note is a block comment. It can continue onto the next line. */ We will use // for everything in this course, since one short note per line is all our programs need, but it is worth recognising /* and */ when we meet them in other people's code.

Writing a Note Above the Code

The most common place for a comment is on its own line, directly above the code it describes. Here is a greeting for the Corner Cafe with a note above it: JavaScript // This program greets a customer at a coffee shop console.log("Welcome to the Corner Cafe!"); When we run this, only the greeting appears: text Welcome to the Corner Cafe! The comment line produced nothing, because JavaScript never looked at it. It is there purely for whoever reads the file next - which is very often us, a week later, wondering what we were thinking.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

A comment does not have to take up a whole line. We can also add one at the end of a line of code, after the semicolon:

JavaScript

console.log("Today's special is a caramel latte."); // inline note about the special

console.log("Today's special is a caramel latte."); // inline note about the special

Everything before the // runs as normal; everything after it is ignored. We call this an inline comment. It is handy for a short remark about a single line, when a whole line of explanation would feel like too much.

text

Today's special is a caramel latte.

Today's special is a caramel latte.

The output is exactly the same as it would be without the comment. An explanatory comment like this one never changes what a program does; it only changes how easy the program is to understand. There is one deliberate exception, and it is the next thing we learn.

Because JavaScript ignores anything after //, comments give us a neat trick: we can put // in front of a line of code to switch that line off without deleting it. Programmers call this commenting out a line.

JavaScript

// The line below is disabled, so it does not run
// console.log("This message stays hidden.");

// The line below is disabled, so it does not run
// console.log("This message stays hidden.");

The second line looks like code, but the // at the front turns it into a comment, so the message never appears. This is useful when we want to test a program without one of its lines, or keep a line around for later. To switch the line back on, we simply remove the //.

Comments are one half of readable code. The other half is layout. Two habits make a big difference:

Blank lines between groups. A blank line costs nothing and lets the eye see where one idea ends and the next begins. JavaScript ignores blank lines just as it ignores comments.
One instruction per line. JavaScript would let us cram several instructions onto a single line, but a reader has to untangle them. One line, one instruction, one semicolon.

Here is our full Corner Cafe program with everything in place:

JavaScript

// This program greets a customer at a coffee shop
console.log("Welcome to the Corner Cafe!");

// The line below is disabled, so it does not run
// console.log("This message stays hidden.");

console.log("Today's special is a caramel latte."); // inline note about the special

// This program greets a customer at a coffee shop
console.log("Welcome to the Corner Cafe!");

// The line below is disabled, so it does not run
// console.log("This message stays hidden.");

console.log("Today's special is a caramel latte."); // inline note about the special

When we click Run, only two lines appear, because one console.log is switched off and the rest are comments:

text

Welcome to the Corner Cafe!
Today's special is a caramel latte.

Welcome to the Corner Cafe!
Today's special is a caramel latte.

Read the code again from the top. Even without knowing much JavaScript yet, the comments and the spacing make it clear what each part is for. That is the goal.

There is one special kind of comment that programmers everywhere recognise. When we know a piece of code still has to be written, we leave a comment starting with the word TODO, followed by a short description of the missing work:

JavaScript

// TODO: Print the opening hours here

// TODO: Print the opening hours here

The word TODO is not special to JavaScript - it is still just a comment, and the program ignores it. It is special to people: it is a widely shared signal that says "something belongs here, and it is not done yet". From the next unit onward, the practice tasks in this path will use TODO comments to show us exactly where our code should go. When we see one, that is our cue to write code in its place.

Great work! In this lesson, we learned that a comment starts with // and runs to the end of the line, that JavaScript ignores comments entirely, and that we can write a comment on its own line or at the end of a line of code. We used // to switch a line off without deleting it, saw how blank lines and one instruction per line keep a program readable, and met the TODO convention that marks work still to be done.

Next up are a few practice tasks where we add notes to a program, hide a line, and tidy up a cramped file. Comments are easy to write and easy to skip, so this is a great chance to build the habit early. Let's keep going!

Introduction

What Is a Comment?

Writing a Note Above the Code

Join the 1M+ learners on CodeSignal

Notes at the End of a Line

Switching a Line Off

Giving the Program Room to Breathe

Leaving Ourselves a TODO

Conclusion and Next Steps