ASDoc will fail if your code contains non-UTF-8 characters.
Comment text should always precede any @ tags
If the comment text is not placed above the @ tag it is interpreted as an argument to the @ tag. The @private tag, however, can be placed anywhere in the ASDoc comment.Best practices for commenting variables with ASDoc
Describe how the variable will be used
Create comments that contain useful information about how the variable will be used. Describe the "why" rather than the "what".Best practices for commenting methods and interfaces with ASDoc
Create useful comments for all methods and interfaces
Place the comment directly above the method declaration. Outline the method's purpose and any implementation details. Try to avoid simply stating what the method does. Optionally explain the reasoning for the method's return value and also any arguments the method may take.Best practices for commenting events with ASDoc
Use fully qualified classpaths for event types
This will ensure that the event is completely unique and that it will not collide with events from elsewhere in the system. For example, consider a project in which you add third-party code is added to an application; using fully qualified classpaths ensures that your application's events are unique.
For example: com.seantheflexguy.burrow.events.RSSDataEvent
Flex applications are complex systems that greatly benefit from thoughtful planning. Use proven methodologies to ensure the application being built is structurally sound.
Create use cases
Generate use cases for each goal or task in the application. Define the use cases from the perspective of an Actor. Typically, an Actor is simply a user of the application you are building. A use case can be created around any interaction that a user performs. Actors can also be the application itself, another application, or an outside system such as a web server.
Consider using UML
Describing the application's main classes and data model using the Unified Modeling Language (UML) can help refine the objects in your application and avoid potential rework to the code later.
Consider using code generation
There are a number of tools that will generate ActionScript 3.0 source code from UML diagrams. This can save time in some cases. Two tools worth investigating are Enterprise Architect from Sparx Systems and the free Violet ActionScript 3 Generator (VASGen).
Consider using design patterns
Two great books to have in your library are: Design Patterns: Elements of Reusable Object-Oriented Software and Head First Design Patterns.