Learning ActionScript 2.0 in Adobe Flash
Best Practices and Coding Conventions for ActionScript 2.0 > Using comments in your code > Writing good comments

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

View comments on LiveDocs