Sean is a highly sought after Flex developer and consultant with extensive ActionScript programming experience, including more than five years developing for the Flash platform and over a decade of experience designing and developing desktop and web based applications. Business owner, technical author, blogger and Adobe Flex/AIR enthusiast, Sean is an Adobe Flex Developer Community Champion and the creator of the ActionScript Cheatsheets. Sean has posted 2 posts at DZone. View Full User Profile

Flex best practices – Part 2: Development practices

03.16.2009
| 50561 views |
  • submit to reddit

Commenting ActionScript source code for ASDoc

Placing comments in source code helps explain what the code does and why it exists. Using ASDoc is an excellent way to create and maintain living documentation for a codebase. You can use the comments that reside in the code to facilitate code updates and also to produce the documentation using the ASDoc tool.

Note: In some cases, high-pressure deadlines make it impossible to thoroughly comment your code during the software development process. When deciding if you should skip commenting, weigh the benefits and drawbacks for your project and your current situation.

Best practices for formatting comments

checkmark Follow the standard ASDoc commenting format used below:

/**

 *

 * ASDoc documentation comment.

 *

 * <p>Another chunk of information related to this code block.</p>

 *

 */

checkmark Use white space and leading asterisks to make comments more readable

Tidy up the comments so they do not clutter the source code. This improves readability for other developers working with the source code.

checkmark Use supported HTML to format the ASDoc output

Use any of the HTML tags that ASDoc supports to improve the readability of documentation comments rendered via the HTML files that ASDoc creates.

checkmark Write a complete and concise first sentence of the main description

The first sentence of the main description of the ASDoc comment should contain a concise but complete description for the item being declared. This sentence will be used to populate the summary table at the top of the ASDoc HTML page for this item's class.

Best practices for commenting classes with ASDoc

checkmark Create useful comments for each and every class

Place the comment directly above the class declaration. Outline the code's functionality and note any relationships to other classes. Describe why inheritance relationships exist.

checkmark Use @private for hiding classes from ASDoc

If the class should not be documented use the @private tag anywhere in the comment.

checkmark Use @return if the method has a return type

If a method has a return value, use @return to provide an explanation of the value being returned.

checkmark Use @see for items that have relationships

If the item you are commenting has relationships to other classes or packages use the @see tag to explain these relationships.

checkmark

Published at DZone with permission of its author, Sean Moore.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)