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
TODOnote 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:
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:
When we run this, only the greeting appears:
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.
Notes at the End of a Line
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:
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.
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.
Switching a Line Off
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.
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 //.
Giving the Program Room to Breathe
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:
When we click Run, only two lines appear, because one console.log is switched off and the rest are comments:
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.
Leaving Ourselves a TODO
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:
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.
Conclusion and Next Steps
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!
