User Guide

Using classes and ActionScript 2.0 103
There are two kinds of comments in a typical class or interface file: documentation comments and
implementation comments. Documentation comments are used to describe the code’s specifications
and do not describe the implementation. Implementation comments are used to comment out
code or to comment on the implementation of particular sections of code. The two kinds of
comments use slightly different delimiters. Documentation comments are delimited with /** and
*/, and implementation comments are delimited with /* and */. For more information on why
comments are included in code, see “Using comments in code” on page 77.
Documentation comments are used to describe interfaces, classes, methods, and constructors.
Include one documentation comment per class, interface, or member, and place it directly before
the declaration. If you have additional information to document that does not fit into the
documentation comments, use implementation comments (in the format of block comments or
single-line comments, described next). Implementation comments directly follow the declaration.
Note: Do not include comments that do not directly relate to the class being read. For example, do
not include comments that describe the corresponding package.
Block comments
These comments describe files, data structures, methods, and descriptions of
files. Place a blank line before a block comment. They are usually placed at the beginning of a file
and before or within a method. The following ActionScript is an example of a block comment.
/*
Block comment
*/
Single-line comments
These comments are typically used to explain a small code snippet. You
can use single-line comments for any short comments that fit on a single line. The following
example includes a single-line comment:
while (condition) {
// handle condition with statements
}
Trailing comments
These comments appear on the same line as your ActionScript code. Space
the comments to the right, so they can be distinguished from the code. Try to have the comments
line up with each other, if possible, as the following code shows:
var myAge:Number = 27; //my age
var myCountry:String = "Canada"; //my country
var myCoffee:String = "black"; //my coffee preference
For more information on spacing and formatting, see “Spacing and readability” on page 81.
Wrapping lines of code
Sometimes your expressions do not fit on a single line. Using word wrap in the Script pane or
ActionScript editor solves this problem, but sometimes you have to break expressions, particularly
when code is printed on a page or in an electronic document. Use the following guidelines when
breaking lines of code:
• Break a line before an operator.
• Break a line after a comma.
• Align the second line with the start of the expression on the previous line of code.