So-called comments are text that is ignored by the interpreter but entered by the programmer specifically for the benefit of humans reading the code. Comments should be used liberally to explain what the code does, provide version control information, or describe other relevant information, such as how a data structure is being used or why certain programming choices were made. Comments should describe your code at the conceptual level, not merely mirror the syntax of the code itself. For example, the following comment is useless:
// Set x equal to 5 var x = 5;
whereas the following comment tells us why we're setting x to 5, which helps us follow the flow of the code:
// Initialize our player's x position var x = 5;
Note that you can go a long way toward making your code "self-commenting" by using descriptive variable names and handler names. Consider which of the following is clearer:
x = y / z; // This is very cryptic average = sum / numberOfItems; // This hardly needs explanation
ActionScript supports both one-line comments and extended, multiline comments. One-liners, as we've seen throughout this book, begin with two forward slashes (// ):
// Ah, human contact...this will never be read by the interpreter
One-line comments are automatically terminated by the line break at the end of the line. You must repeat the // characters to add more comment text on the following line:
// Here is the start of a comment... // ...and here's some more of it.
One-line comments can also follow real code on the same line:
var x; // This is a valid comment on the same line as code
ActionScript also supports multiline comments, used to accommodate larger blocks of code commentary, that are not terminated by line breaks. Multiline comments start with the two-character sequence /* and continue until the terminating two-character sequence */ is encountered, as in:
/* -----BEGIN VERSION CONTROL INFO---- Name: MyApplication, Version 1.3.1 Author: Killa Programma Last Modified: August 07, 2002 ------END VERSION CONTROL INFO----- */
Multiline comments are available only in Expert Mode in the Actions panel or in external .as source files included via the #include directive. Multiline comments are converted to single-line comments when you switch from Expert Mode to Normal Mode. In Flash MX, switching back to Expert Mode restores multiline comments. Note that nested comments are legal:
/* This is an example of /* a nested // comment */ /* This another /* example of nested comment */ The comment doesn't end until the second terminator is encountered here */
The following is avoided by convention, but it is valid:
/* This comment is followed by real code */ var x = 5;
When making major (or even minor) revisions to some code, it is common practice to include your initials and the date of the change in a comment, such as this:
// Fixed error in financial calculation. BAE 12-04-02. V1.01
Comments let us temporarily disable code (or permanently disable old code) instead of deleting it. Disabling code by making it into a comment is known as commenting out the code. It is easy to reenable the code by removing the comment delimiters:
/* Disable this block of code until I change my mind
duplicateMovieClip("character", "newCharacter", 1);
newCharacter._rotation = 90;
*/
You can disable a single line of code by simply preceding it with two slashes:
// newCharacter._rotation = 90;