MACROMEDIA FLASH 8-LEARNING ACTIONSCRIPT 2.0 IN FLASH, Руководство пользователя

Страница: 744 / 830

744 Best Practices and Coding Conventions for ActionScript 2.0
■
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.
Adding comments to classes
The two kinds of comments in a typical class or interface file are documentation comments and
implementation comments .
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/2004
copyright Macromedia, Inc.
*/
After the documentation comments, declare the class. Implementation comments should
directly follow the declaration.
NO
T
E
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.
NO
TE
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.
NO
T
E
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.