Comments

Finally, a very important aspect of good programming style is commenting your code. Commenting allows you to insert remarks and commentary directly in source code, making it more readable to yourself as well as to others. Any comments you include will be ignored by the JavaScript interpreter. Comments in JavaScript are similar to those in C++ and Java. There are two types of comments: those that run to the end of the current line and those that span multiple lines. Single-line comments begin with a double foreslash (//), causing the interpreter to ignore everything from that point to the end of the line. For example:

var count = 10;    // holds number of items the user wishes to purchase

Comments spanning multiple lines are enclosed C-style between a slash-asterisk (/*) and asterisk-slash (*/) pair. The following example illustrates both types of comments:

/* The function square expects a numeric argument and returns the value squared.
   For example, to square 10 and place the value in a variable called y, 
   invoke it as follows:
   var y = square(10);
   This function should only be called with numeric arguments!
*/
function square(x) 
{
   return x*x;              // multiply x times x, and return the value
}

Everything between /* and */ is ignored by the interpreter. Note that you cannot nest multiline comments. Doing so will cause an error:

/* These are 
/* nested comments and will
*/  
definitely cause an error! */

It cannot be stressed enough how important commenting is to writing good code. Comments should add information that is not immediately apparent from the code itself. For example, it is always good style to include a comment for each function you define, detailing the values the function expects, the operation it performs, side effects it might incur, and the type of the value it returns. Complicated statements or loops should always be commented, as should any objects that you create for your own use. In addition, an introductory comment should be included in each script to indicate its purpose and any known bugs or concerns with the code it contains.

Commenting makes code easier for others to understand. Most programmers’ worst nightmare is to be assigned to fix or maintain large pieces of uncommented code. You can save your successor hours of work by including your logic and reasoning in the code you write. Professional programmers always comment their code, especially in a mercurial environment like the Web.

Commenting also makes code easier for you to understand. Anyone who has spent any significant length of time writing software can tell you about a time they came back to an old piece of code they wrote that completely baffled them. You are not going to remember the details and subtleties of the task at hand forever. If only for your own sake, be sure to include comments in your scripts.