Comments (ActionScript: The Definitive Guide)

14.3. Comments

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 i equal to 5
i = 5;

whereas the following comment tells us why we're setting i to 5, which helps us follow the flow of the code:

// Initialize our counter, used to search
// the password string starting at index 5
var i = 5;

Note that you can go a long way toward making your code "self-commenting" by using descriptive variable names and handler names. 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, 2000
   ------END VERSION CONTROL INFO-----
*/

Multiline comments are available only in Expert Mode in the Flash 5 ActionScript editor 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. Note that nested comments are legal:

/* This is
/* a nested // comment */

The following is not used by convention, but it is valid:

/* This comment is followed by real code */ var x = 5;

It is common practice to include your initials and the date of the change in a comment whenever making major (or even minor) revisions to some code, such as this:

// Fixed error in financial calculation. BAE 12-04-00. 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 re-enable 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;