ActionScript: The Definitive Guide

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 ...