Commenting Your Code - MACROMEDIA FLASH MEDIA SERVER 2-DEVELOPING MEDIA Develop Manual

For more information on strict typing and code hints, see Learning ActionScript 2.0 in Flash or
search for "strict data typing" or "code hints" in Flash Help.

Commenting your code

Always comment code in an application. Comments are the author's opportunity to tell a
story about what the code was written to do. Comments should document every decision that
you make while you build an application. At each point where a choice is made about how to
code the application, place a comment describing that choice and why it was made.
When you write code that is a work-around for a specific issue, add a comment that will make
the issue clear to future developers who may be looking at the code. This makes it easier for
them to address that issue.
The following is an example of a simple comment for a variable:
var clicks:Number = 0; // variable for number of button clicks
Block comments are useful when a comment contains a large amount of text:
/*
Initialize the clicks variable that keeps track of the number of times
the button was clicked.
*/
Some common methods for indicating specific topics are:
// :TODO: topic
Indicates that there is more to do here.
// :BUG: [bugid] topic
Shows a known issue here. The comment should also explain the issue and give a bug ID
if applicable.
// :KLUDGE:
Indicates that the following code is not elegant or does not conform to best practices. This
comment alerts others to provide suggestions about how to code it differently next time.
// :TRICKY:
Notifies developers that the subsequent code has a lot of interactions. Also advises
developers that they should think twice before trying to modify it.
Coding conventions 103