Using Comments in Your Code

This section describes how to use comments in your code. Comments document the decisions you make in the code, answering both how and why. For example, you might describe a workaround in comments. Another developer would be able to find the related code easily for updating or fixing. And finally, the issue might be addressed in a future version of Flash or Flash Player, hence the workaround would no longer be necessary.

Writing Good Comments

Using comments consistently in your ActionScript 2.0 code allows you to describe complex areas of code or important interactions that are not otherwise clear. Comments must clearly explain the intent of the code and not just translate the code. If something is not readily obvious in the code, add comments to it.

If you use the Auto Format tool with your code, you will notice that trailing comments move to the next line. You can add these comments after you format your code, or you must modify the comment’s new placement after you use the Auto Format tool.

For information on using comments in classes, see the next section, “Adding Comments to Classes.”

Use the following guidelines when you add comments to your code:

• Use block comments (/* and */) for multiline comments and single-line comments (//) for short comments. You can also use a trailing comment on the same line as the ActionScript code if necessary.
• Make sure you don’t use comments to translate your ActionScript code. You don’t need to comment on elements that are obvious in the ActionScript code.
• Comment on elements that are not readily obvious in the code. In particular, add comments when the subject is not described in the surrounding paragraphs.
• Do not use cluttered comments. A line of cluttered comments often contains equal signs (=) or asterisks (*). Instead, use white space to separate your comments from ActionScript code.

Note: If you use the Auto Format tool to format ActionScript, you remove the white space. Remember to add it back or use single-line comments (//) to maintain spacing; these lines are easy to remove after you format your code.

• Remove any superfluous comments from the code before you deploy your project. If you find that you have many comments in your ActionScript code, consider whether you need to rewrite some of it. If you feel you must include many comments about how the ActionScript code works, it is usually a sign of poorly written code.

Note: Using comments is most important in ActionScript code that is intended to teach an audience. For example, add comments to your code if you are creating sample applications for the purpose of teaching Flash, or if you are writing tutorials about ActionScript code.

Adding Comments to Classes

The two kinds of comments in a typical class or interface file are documentation comments and implementation comments.

Note: Documentation and implementation comments are not formally represented in the ActionScript language. However, they are commonly used by developers when writing class and interface files.

You use documentation comments to describe the code’s specifications, but not the implementation. You use implementation comments to comment out code or to comment on the implementation of particular sections of code. Documentation comments are delimited with /** and */, and implementation comments are delimited with /* and */.

Use documentation comments 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).

Start classes with a standard comment, which uses the following format:

/**
    User class
    version 1.2
    3/21/2006
    Copyright Adobe Systems, Inc.
  */  

After the documentation comments, declare the class. Implementation comments should directly follow the declaration.

Note: Don’t include comments that do not directly relate to the class that’s being read. For example, don’t include comments that describe the corresponding package.

Use block, single-line, and trailing comments within the body of your class to comment on your ActionScript code.