User Guide

General coding conventions 77
For more information on formatting code, see the following topics:
• “Using comments in code” on page 77
• “Using code completion and suffixes” on page 78
• “Using recommended suffixes” on page 80
• “Spacing and readability” on page 81
Using comments in code
One of most important aspects of any project, whether it is a simple widget or a large scale
application, is documentation. Without comments, it is likely you will not know why code was
written or organized in a certain way. For this reason, it is important to thoroughly document
your code in key points of the application. For example, if you must write a certain workaround
for a complicated situation, document what you are doing and why. Whoever works with the
code in the future can understand what is happening and might not inadvertently break that
code.
Consistently use comments in your ActionScript, and describe what the code is doing. Using
comments is useful to help you remember coding decisions, and it is extremely helpful for anyone
else reading your code. Comments must clearly explain the intent of the code and not just
translate the code. If something is not readily obvious in the code, you should add comments to
it.
Avoid using cluttered comments, despite how popular they sometimes are to add. An example of
cluttered comments is a line of equal signs (=) or asterisks (*) used to create a block or separation
around your comments. Instead, use white space to separate your comments from the
ActionScript. If you format your ActionScript using the Auto Format tool, this removes the white
space. Remember to add it back in or use single comment lines (//) to maintain spacing; these
lines are easy to remove after you format your code.
Before you deploy your project, remove any superfluous comments from the code. If you find
that you have many comments in the ActionScript, consider whether you need to rewrite some of
the ActionScript. If you feel you must include many comments about how the code works, it is
usually a sign of inelegant ActionScript.
Note: Using comments is most important in ActionScript 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 documentation on ActionScript.
Comments document the decisions you make in the code, answering both how and why. For
example, you might describe a workaround in comments. Therefore, the related code is easily
found for updating or fixing at a later date, by another developer, or if the issue is addressed in a
future version of Flash or Flash Player and the workaround is no longer necessary.
Use block comments for multiline comments, as the following example shows:
/*
The following ActionScript initializes variables used in the main and sub-
menu systems. Variables are used to track what options are clicked.
*/