Code Comments

The phone store employee might jot down some notes on the features of a newly released phone or on the new plans her company offers. These notes are only for the employee — they’re not for customers to read. Nevertheless, these notes help the employee do her job better by documenting the hows and whys of what she should tell customers.

One of the most important lessons you can learn about writing code is that it’s not just for the computer. Code is every bit as much, if not more, for the developer as it is for the compiler.

Your computer only cares about machine code, a series of binary 0s and 1s, that comes from compilation. There’s a nearly infinite number of programs you could write that yield the same series of 0s and 1s. The choices you make about how to write your program matter — not only to you, but to your other team members and even to your future self.

You should strive not just to write programs that work correctly, but programs that make sense when examined. You can go a long way in that effort by choosing good names for your variables (see “Variables”) and functions (see “Functions”).

But another important part is code comments. These are bits of text in your program that are inserted purely to explain things to a human. The interpreter/compiler will always ignore these comments.

There are lots of opinions on what makes well-commented code; we can’t really define absolute universal rules. But some observations and guidelines are quite useful:

• Code without comments is suboptimal.
• Too many comments (one per line, for example) is probably a sign of poorly written code.
• Comments should explain why, not what. They can optionally explain how if that’s particularly confusing.

In JavaScript, there are two types of comments possible: a single-line comment and a multiline comment.

Consider:

// This is a single-line comment
/* But this is
       a multiline
             comment.
                      */

The // single-line comment is appropriate if you’re going to put a comment right above a single statement, or even at the end of a line. Everything on the line after the // is treated as the comment (and thus ignored by the compiler), all the way to the end of the line. There’s no restriction to what can appear inside a single-line comment.

Consider:

var a = 42;        // 42 is the meaning of life

The /* .. */ multiline comment is appropriate if you have several lines worth of explanation to make in your comment.

Here’s a common usage of multiline comments:

/* The following value is used because
   it has been shown that it answers
   every question in the universe. */
var a = 42;

It can also appear anywhere on a line, even in the middle of a line, because the */ ends it. For example:

var a = /* arbitrary value */ 42;
console.log( a );    // 42

The only thing that cannot appear inside a multiline comment is a */, because that would be interpreted to end the comment.

You will definitely want to begin your learning of programming by starting off with the habit of commenting code. Throughout the rest of this chapter, you’ll see I use comments to explain things, so do the same in your own practice. Trust me, everyone who reads your code will thank you!