Agile Enterprise Application Development with Flex

Project Documentation

Programmers don’t like writing comments. They know how their code works. At least, they think they do. Six months down the road, they will be wondering, “Man, did I actually write this myself? What was I planning to do here?”

Program documentation is as important as the code itself. If you are managing the project, make sure that you encourage and enforce proper documentation. Some developers will tell you that their code is self-explanatory. Don’t buy this. Tomorrow, these developers won’t be around, for whatever reason, and someone else will have to read their code.

Program Documentation with ASDoc

Flex comes with ASDoc, a tool that works similarly to JavaDoc, which is well known in the Java community. ASDoc reads the comments placed between the symbols /** and */; reads the names of the classes, interfaces, methods, styles, and properties from the code; and generates easily viewable help files.

The source code of the Flex framework itself is available, too. Just Ctrl-click on any class name in Flash Builder, and you’ll see the source code of this ActionScript class or MXML object. Example 4-3 is the beginning of the source code of the Flex Button component.

Example 4-3. A fragment of the Button source code

package mx.controls
{

import flash.display.DisplayObject;
import flash.events.Event;
...

/**
 *  The Button control is a commonly used rectangular button.
 *  Button controls look like they can be pressed.
 *  They can have a text label, an icon, or both on their face.
 *
 *  Buttons typically use event listeners to perform an action
 *  when the user selects the control. When a user clicks the mouse
 *  on a Button control, and the Button control is enabled,
 *  it dispatches a click event and a buttonDown event.
 *  A button always dispatches events such as the mouseMove,
 *  mouseOver, mouseOut, rollOver,rollOut, mouseDown, and
 *  mouseUp events whether enabled or disabled.
 *
 *  You can customize the look of a Button control
 *  and change its functionality from a push button to a toggle button.
 *  You can change the button appearance by using a skin
 *  for each of the button's states.
 */
public class Button extends UIComponent
       implements IDataRenderer, IDropInListItemRenderer,
       IFocusManagerComponent, IListItemRenderer,
       IFontContextComponent, IButton
{
    include "../core/Version.as";

    /**
     *  @private
     *  Placeholder for mixin by ButtonAccImpl.
     */
    mx_internal static var createAccessibilityImplementation:Function;

    /**
     *  Constructor.
     */
    public function Button(){
        super();

        // DisplayObjectContainer properties. Setting mouseChildren
        // to false ensures that mouse events are dispatched from the
        // button itself, not from its skins, icons, or TextField.
        // One reason for doing this is that if you press the mouse button
        // while over the TextField and release the mouse button while over
        // a skin or icon, we want the player to dispatch a "click" event.
        // Another is that if mouseChildren were true and someone uses
        // Sprites rather than Shapes for the skins or icons,
        // then we we wouldn't get a click because the current skin or icon
        // changes between the mouseDown and the mouseUp.
        // (This doesn't happen even when mouseChildren is true if the skins
        // and icons are Shapes, because Shapes never dispatch mouse events;
        // they are dispatched from the Button in this case.)

        mouseChildren = false;

Beside the /** and */ symbols, you have a small number of the markup elements that ASDoc understands (@see, @param, @example).

The beginning of the Help screen created by the ASDoc utility based on the source code of the Button class looks like Figure 4-14.

Figure 4-14. A fragment of the Help screen for Button

Detailed information on how to use ASDoc is available at http://blogs.adobe.com/flexdoc/2009/01/updated_doc_on_using_the_flex_1.html.

Documenting MXML with ASDoc has not been implemented yet, but is planned to be released with Flex 4. The functional design specifications of the new ASDoc are already published at the Adobe open source site.

UML Diagrams

Unified Modeling Language (UML) diagrams are convenient for representing relationships among the components of your application. There are a number of tools that turn the creation of diagrams into a simple drag-and-drop process. After creating a class diagram, these tools allow you to generate code in a number of programming languages.

In a perfect world, any change in the class definition would be done in the UML tool first, followed by the code generation. Future manual additions to these classes wouldn’t get overwritten by subsequent code generations if the model changes.

UML tools are also handy in situations where you need to become familiar with poorly commented code written by someone else. In this case, the process of reverse engineering will allow you to create a UML diagram of all the classes and their relationships from the existing code.

There are a number of free UML tools that understand ActionScript 3 (UMLet, VASGen, Cairngen) with limited abilities for code generation.

Commercial tools offer more features and are modestly priced. Figure 4-15 shows a class diagram created by Enterprise Architect from Sparx Systems. This diagram was created by autoreverse engineering of the existing ActionScript classes.

Figure 4-15. Enterprise Architect: a UML class diagram

The process is pretty straightforward: create a new project and a new class diagram, then right-click anywhere on the background, select the menu item “Import from source files,” and point at the directory where your ActionScript classes are located. The tool supports ActionScript, Java, C#, C++, PHP, and other languages.