As with HTML & CSS, it is good practice to comment your code: not only for yourself, but also for anyone who might come after you. Comments also have other uses in development, which I’ll explain at the end of this article.

Single-Line JavaScript Comments

Any text or code on a single line can be turned into a comment by preceding it with two forward slashes:

// this is a single-line comment

While this works well for brief descriptions or to comment out one line of non-functional code, it doesn’t provide the space needed for longer explanations. In addition, there is a small risk that a long single-line comment will accidentally catch an errant carriage return and accidentally break over two lines. If that happens, the second uncommented line will cause a syntax error.

Multi-Line JavaScript Comments

Multi-line comments in JavaScript are exactly the same as those in CSS:

/* this is a
multi-line comment */

Multi-line comments are obviously much more flexible than the single line version.

Using Comments In Development

Comments are not only useful for leaving notes and reminders, but for temporarily removing problematic code from execution:

function pill(dose) {
bottle++;
// gulp++; this commented line will not be executed
}

This can be very useful, but of course you must be careful in only commenting out code that you don’t want to run.

IE Oddities: Conditional Compilation

Like HTML conditional comments, Internet Explorer version 10 and below (and only IE) will run code in JavaScript comments if the comment starts with a /*@cc_on @*/ statement. This can be used to target earlier versions of IE with JavaScript without affecting other browsers. More information on conditional compilation can be found at the Microsoft Internet Explorer Dev Center.

Removing Comments For Production

It’s a good and common practice to strip comments, whitespace and any unused code from scripts before deploying them on a live site, to minimize file size and load time. Tools such as Uglify.js can do this automatically in a build process; alternatively, an online JS minifier can be employed. Of course, it’s vital to preserve the original fully formatted and commented code for future work.

“What If I Want To Preserve Some Comments In Minified JS Code?”

In certain cases you might want to preserve some comments in your scripts, such as those containing copyright claims, developer credits and licensing information, while removing all others. Many minifiers will preserve JS comments if they contain one of two character strings:

So a comment that included the following:

/* @preserve
A shoutout to all my West Side homies. Nerds4Lyfe.
*/

Would be retained as a comment (sans the @preserve keyword) in the minified, production version of the JavaScript code.

Photograph by Simon Matzinger, licensed under Creative Commons

Enjoy this piece? I invite you to follow me at twitter.com/dudleystorey to learn more.