Flex best practices – Part 2: Development practices
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
Follow the standard ASDoc commenting format used below:
* ASDoc documentation comment.
* <p>Another chunk of information related to this code block.</p>
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.
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.
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
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.
Use @private for hiding classes from ASDoc
If the class should not be documented use the @private tag anywhere in the comment.
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.
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.
(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)