Programming Basics - JavaScript: Novice to Ninja - page 24

Comments
Our first task on our journey to becoming a JavaScript ninja is learning how to write com-
ments in JavaScript. This may seem a strange place to start, because in programming a com-
ment is a piece of code that is ignored by the language―it doesn't do anything. Despite this,
comments are extremely important: well-commented code is the hallmark of a ninja pro-
grammer. It makes it easier for anybody reading your code to understand what's going on,
and that includes you! Believe me, you'll be thankful you commented your code when you
come back to read it after a few weeks. You only need to write enough so that it's clear what
the code is supposed to do.
In JavaScript there are two types of comment.
Single line comments start with // and finish at the end of the line:
// this is a short comment
Multiline comments start with /* and finish with */ :
/* This is a longer comment
anything here will be ignored
This is a useful place to put notes
*/
It's good practice to write comments in your code. There are even utilities that can take
your comments and produce documentation from them such as JSDoc Toolkit , Docco , and
YUIDoc . You'll see lots of comments throughout the code in this topic.