ActionScript Graphic Cookbook
Backx, Peter and Gélineau, Dominic
2012, Packt Publishing
978-1-84969-320-2

This is a cookbook, a book of recipes; it is not a reference or teaching book; you will not have a comprehensive library at the end. This book give specific solutions to specific needs. A teaching book might show a finished chart with call-outs explaining how to create or configure the pieces, but a recipe is not an analysis: it starts with the least foundation it can and works towards a finished graphic. This book will show you how to create graphic representations of data; it will not tell you when to use a particular technique.

It is also not a users’ manual for the Data Visualization chart library from Adobe, although the recipes in the middle of the book use that library. For simple line charts (e.g. sparklines), the recipe describes how to draw the lines oneself using the ActionScript graphic primitives. For advanced rotatable 3-D charts (which Data Visualization does not support) and 3-D landscapes, it uses advanced geometry and low-level polygon fills. While these are not Flex components (the code is pure ActionScript with mostly Sprite-based classes, many recipes are connected to data, sometimes dynamically.

Each recipe presents as a set of sections: the title, Getting ready, How to do it…, How it works…, There’s more…, and See also. Besides the inconsistent use of ellipsis, the title section (which describes the need) is often perfunctory and sometimes omits a picture of the finished graph or chart (i.e. the tempting photo of the finished dish). While some How it works… sections show additional (but too few) images, a graphics book should err on their side of too many images, and certainly should always have one as part of the recipe’s description.

Within sections, some of the recipes do built on the previous one a bit: graphic enhancements, adding different data sources, or using a more complex representations. The sections cover

• Drawing with the core ActionScript objects
• Representing sets of data in graphs
• Bar charts (using Adobe’s Data Visualization library)
• Advanced charts without the Data Visualization library
• Charting Data on Maps
• Animation and Zooming in on Data
• Showing Network Data Relationships Graphically
• Rotatable 3-D Charts and Data Landscapes

The book is available in Kindle and paperback editions as well as PDF, mobi, and epub direct from the publisher. The PDF seems to be images of the pages, not text (no copy-and-paste, no external links, and no links from the table of contents). It is also available on-line from the publisher’s site once purchased. The HTML presentation, often being very wide, actually makes the chapters easier to read than the book format: the code does not need to wrap; the images are visible on the same “page” as the rest of the recipe, and the links work.

Some recipes need to import data from files or web services and include code and discussion to do so; these pedestrian routines (and some entire recipes!) distract from the topic of graphic functionality; perhaps they could have been relegated to an appendix. Some recipes, perhaps acknowledging that supporting code is large and tedious, direct the user to download files from the Packt Publishing website and “… follow along”.  The index is 12 pages long; very respectable for a 280 page book.

For its niche, it is likely the definitive reference. It does not address the relative merits of using a well-known charting library vs. using trigonometric functions and low-level drawing functions; clearly these include abstraction and performance. Cookbooks don’t offer a questionnaire; they just tell you how to make a great souffle  Joe Bob says: check it out.

I’ve talked about comments in The Zen of Comments, but the rising tide of ASDocs (and JDoc, etc.) brings this home: requiring comments is as pointless as requiring lines-of-code or a minimum number of check-ins. The existence of comments adds nothing to source code; they make it harder to see the code itself and are often out of date.

/**
* this is the current record id
*/
public var currentRecordId : String ="";

/**
* handle search button click
*
* @param event the mouse event from the click
*/
private function searchButtonClickHandler(event : MouseEvent) : void
{
   ...
}

/**
* @return Foo
*/
public function get foo() : Foo
{
    return _foo;
}
/** TODO: fix this
*/
public function clearGlobalList() : void
{
    this.globalList.removeAll();
}
/**
* @param control int
* @param clearAll delete extra items
*
* @return the number of deleted items
*/
public function truncateData(maximumCount : Number) : void
{
    ...
}

A bad comment is worse than no comment. The goal is to add information to the source code, nor obsolete noise, and the best way is to name the variables, objects, and methods so they are self-descriptive. As you can see from the examples above, adding ASDoc headers makes the code less readable, and the names of the variables and functions already completely describe their behavior.

Good Nomenclature is the Best Comment

or

“The proper use of comments is to compensate for our failure to express ourselves in code.” — Robert C. Martin

“If the code and the comments disagree, then both are probably wrong” –attributed to Norm Schryer

“Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed? ‘ Improve the code and then document it to make it even clearer” –Steve McConnell Code Complete

I’m not advocating Hungarian notation. The need to use short variable names has long past, and abbreviating types is more than silly. Perhaps it is a dogged remnant of my sordid past in Pascal: I like complete, explicit names.

• Class names should be specific nouns and avoid words that have meanings in the context of programming (we are running out of terms for “object”!). For example,
• Method names should start with a verb (“open”, “delete”, “calculate”) and contain the names of the classes they are going to act on, e.g. importDetail(aDetail : Detail) : void
• Property and field names should not include their class name (no Client.clientName) unless necessary to differentiate it within the context of the class (Client.clientName and Client.accountName).

Sample Naming Patterns

• function findFoo(criteria) : Foo returns a Foo or null/-1/empty string if not found. I use an “a” prefix on my parameters to differentiate them from local variables and class fields/properties
• function getFoo(criteria) : Foo returns a Foo or throws an exception if not found
• function createFoo(initial data) : Foo returns a new Foo and adds it to the list/collection/model. Throws an exception if the Foo cannot be created (e.g. the key data already exists)
• function openFoo(initial data) : Foo returns an existing Foo that matches the data or returns a new Foo and adds it to the list/collection/model
• function removeFoo(aFoo) : Boolean returns true if aFoo was remove and false if aFoo was not present to remove. throws an exception is aFoo was there but the method could, for some reason, not remove it
• function calculateTotal(fooArray : Array) : Number returns a value based on the parameter. The name indicates that the result is a dynamic value that is not stored persistently and is not based on anything else
• function composeErrorMessage(error : Error, data : Foo, user : User) : String returns text value based on the parameters. The name indicates that the result is a dynamic value that is not stored persistently and is not based on anything else
• class DeletionConfirmationView (not DeleteView or event DeleteConfirmationView). “Delete” is a verb and indicates a function (which is going to delete something). The view is going to present a confirmation dialog for the deletion (the noun form of “delete”).
• function foo(param : type, pleaseDoSomething : Boolean) : void The second parameter is asking the method to do something like delete child objects, suppress notifications. The please makes it clear that it is a parameter, not a field or property of the object. Calling it doSomething or even isDoSomething does not make it clear that it is a parameter

Some bad examples from the Flex framework itself:

• property includeInLayout, visible, includeInLayout - it should be “isIncludedInLayout”.
• properties visible and enabled are at least adjectives, not verbs.

• property countFavorites - it should be favoritesCount. The function that calculates the value might be called “countFavorites()”

One of the evils that OOP freed us from was long parameter lists like this:

wm_op(hdl, 0, 0 , 230, false, false, "false", true, ptr.value)

Even with default parameters and the occasional enumeration, telescoping parameter lists like these are chronic bugs waiting to happen and to regress. The problem was that call was not self-explanatory. Using object properties allows us to see each property’s name as we assign it:

var processor : Processor = new Processor(this);
processor.x = 0;
processor.y = 0;
processor.minHeight = 230;
processor.buttonText = "false";
processor.initialValue = pointer.value;

Instead of entering dummy arguments to allow access to later parameters, the object sets its own defaults.

Every Value a Parameter

The Every-Value-A-Parameter (EVAP) style of constructor design seems to forgo much of the strength of objects. It treats objects as data structures and does not take advantage of their properties’ ability to be internally consistent. The EVAP style passes all the internal values of the object in the constructor’s parameters, and all properties are read-only from that point forward (i.e. an immutable object).

If several parameters in a long list interact with each other or are mutually exclusive, either the constructor fails to create the object (often an opaque exception) or we do not check the interaction until needed (e.g. until a query object was activated). We cannot validate the parameters one-by-one because they all come in at once.

The calling code must also have all the information about the object at once.

var foo : Foo;
if (ref.gah >= 14)
   foo = new Foo(this, ref.gah, null, (container == null) ? null : container.bar);
else
    foo = new Foo(this, 2, null, (container == null) ? null : container.bar);

As shown, a symptom of  EVAP is a mass of trinary expressions (exp ? true : false)  in call parameters, or branches with alternate initializers for the same object. If one could set the new object’s attributes explicitly and individually (i.e. after it was instantiated), then the code branches would be specific to the attributes they affect.

var foo : Foo = new Foo (this);  
 
if (ref.gah > 14)
   foo.gah = ref.gah;
else
   foo.gah = 2;
 
if (container != null)
   foo.bar = container.bar;

A subtler aspect is the ability to allow descendant classes, containers, or helpers to override an object’s configuration. For example, a base query object might have a base query string, but a descendant class or a wrapper class, OracleSQLQuery, might take advantage of Oracle-specific syntax or settings. If the query string must be a read-only constructor parameter, the descendant cannot override an contained object created by its ancestor; at best, it can create a new object, copy every other attribute value, and assign it to a protected reference that the ancestor will (we hope) use.

Special Mutators for Mutually Dependent Properties

Some parameters’ validity depends on other parameters (e.g. height and minHeight). An object can adjust one to fit another, but this can violate a  object’s agreement with the user: a writable parameter value will be what the user set it to.

form.height = 95;
form.minHeight = 80;
...
form.height = 75;
form.minHeight = 70;

If the object unilaterally and silently changes the second value for height to 80 (the minimum), the coder will expect it to be 75. If the object rejected the assignment because it (at the time) violated the minHeight value, then the object will remain internally consistent.
Some properties are mutually dependent, so it is more than a matter of the sequence of assignment. If the object cannot defer the dependency validation (see below), then it can offer a special mutator-like function that accepts both or all of the mutually dependent values at once. Two or three parameters are not too obtuse, especially if the function names them explicitly.

foo.setNameAndPassword(...)
foo.setPosition(x, y);

Deferred or Explicit Validation

A SQLQuery object can allow any value for its queryText and parameters properties until the moment its active property turns true. At that moment, all of the properties must be consistent with each other (i.e. the items in the parameters collection must match the references in the queryText). If something tries to change one of these values in an active query, the object must decide whether to set active to false or to reject the new value (e.g. by throwing an exception).

Another example might be a class URIString, which does not check for validity until something calls function isValid(). The user can set and clear different, mutually-exclusive parts of a URI without raising an exception because their interrelations don’t matter until the validation method runs.

Jeffrey Stylos and Steven Clarke: “Usability Implications of Requiring Parameters in Objects’ Constructors.”ICSE 2007.

Immutable Objects and Internal Consistency

Nevertheless, some objects really want to be immutable. It saves a lot of checking and binding events, allows static caching, and removes the need for a .copy() or .clone() method.

The best of both wolds is an immutable object with a (mutable) builder. The builder object takes all of the initial values as interactive, public properties, optionally validates those values when they are set or just before the builder becomes the immutable constructor’s sole parameter. One might use it like this:

    var builder : Object = ImmutableObject.createBuilder();
    builder.name = "Fred";
    builder.birthMonth = 4;
    builder.birthYear = 1960;
 
    var imm : ImmutableObject = builder.create();

The immutable class and the builder class work together:

1. The class’ static function returns an instance of the builder class
2. The consumer plays with the builder’s properties
3. The consumer has the builder create an instance of the class
4. The builder validates its properties
5. The builder passes itself to the class’ constructor
6. The class initializes its immutable properties (i.e. the private fields) from the builder’s properties
7. The builder passes the new class instance to the consumer

Instead of creating a public builder class for each immutable class and ending up with lots of little class files, we can use an internal class with some casting. Note that while the client code does not have access to the ImmutableObjectBuilder class, it gets an instance of that class (into its Object-type variable), and it cannot treat it like a generic object (e.g. builder.height = 44; gives an error).

public class ImmutableObject
{
    public function ImmutableObject(builder : Object)
    {
        if (builder is ImmutableObjectBuilder)
        {
            builder.validate();
 
            initialize(ImmutableObjectBuilder(builder));
        }
        else
            throw new Error("use ImmutableObject.createBuilder().create()");
    }
 
    private function initialize(builder : ImmutableObjectBuilder) : void
    {
        _name = builder.name;
        _address = builder.address;
        _birthDate = new Date(builder.birthYear, builder.birthMonth);
        _photoUrl = builder.photoUrl;
    }
 
    public static function createBuilder() : ImmutableObjectBuilder
    {
        return new ImmutableObjectBuilder();
    }
 
    public function get name() : String
    {
        return _name;
    }
    private var _name : String = "";
 
    public function get address() : String
    {
        return _address;
    }
    private var _address : String = "";
 
    public function get birthDate() : Date
    {
        return _birthDate;
    }
    private var _birthDate : Date;
 
    public function get photoUrl() : String
    {
        return _photoUrl;
    }
    private var _photoUrl : String = null;
}
 
class ImmutableObjectBuilder
{
    public var name : String = "";
    public var address : String = "";
    public var birthMonth : int;
    public var birthYear : int;
    public var photoUrl : String = null;
 
    public function validate() : void
    {
        if ((name == null) || (StringUtil.trim(name) == ""))
            throw new Error("\"name\" is required");
 
        if ((birthMonth == 0) != (birthYear == 0))
            throw new Error("Both birthMonth and birthYear must be set");
    }
 
    public function create() : ImmutableObject
    {
        return new ImmutableObject(this);
    }
}

The downside to this pattern is that it is a little tricky to subclass.Click to see how

public class Descendant extends ImmutableObject
{
    public function Descendant(builder : Object)
    {
       if (builder is DescendantBuilder)
       {
           builder.validate();
 
                   // this calls the ancestor's initialize()
           super(builder.ancestorBuilder); 
 
                 // we have to cast because the parameter 
                 // cannot be the internal class DescendantBuilder
           initialize(DescendantBuilder(builder));  
        }
        else
            throw new Error("use Descendant.createBuilder().create()");
    }
 
    public function get role() : String
    {
        return _role;
    }
    private var _role : String;
 
    //  we can't virtualize this method because
    //     we won't have access to the AncestorBuilder
    private function initialize(builder : DescendantBuilder) : void
    {
        _role = builder.role;
    }
 
    //      static methods are not inherited, so we do not override
    public static function createBuilder() : DescendantBuilder
    {
        var ancestorClassName : String = getQualifiedSuperclassName(Descendant);
        var ancestorClass : Class = Class(getDefinitionByName(ancestorClassName));
        var ancestorBuilder : Object = ancestorClass.createBuilder();
 
        return new DescendantBuilder(ancestorBuilder);
    }
}
 
class DescendantBuilder
{
    public function DescendantBuilder(ancestorBuilder : Object)
    {
        _ancestorBuilder = ancestorBuilder;
    }
 
    public function get ancestorBuilder() : Object
    {
        return _ancestorBuilder;
    }
    private var _ancestorBuilder : Object;
 
    public function get name() : String
    {
        return _ancestorBuilder.name;    //    proxy
    }
 
    public function set name(value : String) : void
    {
        _ancestorBuilder.name = value;
    }
 
    public function get address() : String
    {
        return _ancestorBuilder.address;    //    proxy
    }
 
    public function set address(value : String) : void
    {
        _ancestorBuilder.name = value;
    }
 
    public function get birthMonth() : int
    {
        return _ancestorBuilder.birthMonth;    //    proxy
    }
 
    public function set birthMonth(value : int) : void
    {
        _ancestorBuilder.birthMonth = value;
    }
 
    public function get birthYear() : int
    {
        return _ancestorBuilder.birthYear;    //    proxy
    }
 
    public function set birthYear(value : int) : void
    {
        _ancestorBuilder.birthYear = value;
    }
 
    public var role : String = null;    //    NOT a proxy
 
    public function validate() : void
    {
        _ancestorBuilder.validate();
 
        if ((role == null) || (StringUtil.trim(role) == ""))
            throw new Error("\"role\" is required");
    }
 
    public function create() : Descendant
    {
        return new Descendant(this);
    }
}

I finally have my car fixed. It is a 2005 Prius (second series) and would sometimes fail to allow the headlights to go into low-beams only. My mechanic could not find the cause and sent me to another mechanic. They spent several hours and determined that I needed a new (expensive) headlight switch, which they would special-order.

They estimated one (1) hour installation and I arraigned to bring the car in before work to wait while they installed it. When I arrived, they said it would be done in 1.5 hours. Hmmm.

Two hours later, I was on my way (late to my morning meeting). They cheerfully explained that they had never done this type of switch before, and that I would not have to pay for the extra time it took them. I snarled under my breath at their presumption that I should be happy that I did not have to pay for them being late.

Until I realized that, as software developers:

• We too give estimates based on the best-case scenario (and we believe it ourselves)
• We too have our clients/employers pay for us to learn new things
• And we do charge them if things take us longer then we said they would

The Model-View-Controller pattern is a convenient way to remember which elements of an application need to know about which other elements. The most common frameworks that implement that pattern in Flex are:

• Cairngorm
• PureMVC
• Matte

Several very able commentators have compared these frameworks:

http://www.asserttrue.com/articles/2007/10/17/silvafug-application-frameworks-presentation

http://mate.asfusion.com/forums/topic.php?id=598

http://www.slideshare.net/Antonos/mvc-pattern-flex-implementation-of-mvc-presentation

My humble contributions to this decision are the following sequence diagram for PureMVC and Cairngorm:

When de-serializing objects from SQL storage, the references between the objects appear as foreign key values. Once each object is initialized with its data, one could immediately use the foreign key values to lookup the other objects and store references to them. Even if the objects do not have reciprocal or circular references, loading the types of objects in the correct sequence — target objects loaded before references to those targets — is fussy and creates a dependency between the schema and the loader. One can wait to do these lookups until after all of objects load, but that implies that one will load all objects.

If one goes a step further, the references can remain null until someone actually needs them. Moreover, an object can supply the foreign references (key values) without retrieving the referenced object at all. This can avoid performing the lookup at all even if the object is re-serialized (which requires those foreign key references).

The pattern stores both the reference to the object and the foreign key value that identifies the object (i.e. its key) and uses accessors and mutators to ensure that only one of the two values is active at a time. The referenced-object accessor do the actual lookup if the object reference does not already exist, and the foreign key mutator will store the new foreign reference key value and clear any existing reference object rather than doing a lookup immediately. Note that both mutators optimize by checking to see if the current value already matches the desired value.

</rant>

private var _otherObjectId : uint = 0;
private var _otherObject : OtherObjectVO = null;
public function get otherObjectId () : uint
{
    if (_otherObject != null)
        return _otherObject.id;
    else
        return _otherObjectId;
}

public function set otherObjectId(value : uint) : void
{    // use the accessor, not the variable
    if (this.otherObjectId != value)
    {
         _otherObjectId = value;
        _otherObject = null;
    }
}

public function get otherObject() : OtherObjectVO
{
    if ((_otherObject == null) && (_otherObjectId != 0))
        _otherObject = goGetTheOtherObject(otherObjectId);

    return _otherObject;
}

public function set otherObject(value : OtherObjectVO) : void
{
    if(_otherObject != value)
    {
        _otherObject = value;
        _otherObjectId = 0;
    }
}

While the otherObject() accessor prevents unnecessary lookups during the object’s de-serialization, the otherObjectId() accessor prevents an unnecessary lookup at the end of an object’s life when it’s being serialized.

With objects that have many references that its client might not every need (e.g. configuration objects), the Lazy Reference Accessor pattern can eliminate unnecessary object loading, saving memory, time, and data access.

I am a manager for a team of developers. One might think that they work for me and I have power over them. I have a boss and so on. But if the real goal is to deliver the product or service of the organization, then the real power is with the people who do the work.

I learned from my father that the real power in an organization is the organization chart turned upside down, at least as far as “power” means actually producing something. It seems obvious when one thinks about it: boxes (people) on the organization chart connected to lots of other boxes are too busy maintaining those connections to do anything else.

So a rational organization rewards maangers that enable their direct reports to do their job better. In other words, my job as a manager is to serve my developers.

I serve them by making sure their computers work and that their chairs are comfortable and that they have the text editor they like and that they get lunch if I ask them to work through the day.

I serve them by making sure they understand their goals and restrictions and priorities. I serve them by removing obstacles from their way. I serve them by keeping my bosses away; my job is to answer their questions and make sure the rest of the company knows what we are doing.

Tech managers do not have to motivate or control staff. Developers want to work, and they want to deliver, and they love seeing their work in use. Managers need to get them on stage in front of the right audience and let them shine.

Joel’s 12-Point list, points 2 and 3 talk about building the application cleanly and regularly. He is talking about building it on a build machine. I emphasis this because, as a manager, I have to gently remind my happy minions that “it works on my machine” is more of a problem than an explanation.

If the coder is working on several different projects, they might find that some library for project A has a namespace collision with a library B. VMWare or the like is often a good solution: each project has their own environment. As the software is running on the same “machine”, installing it into each virtual environment seems like an ethical choice.

More likely, the coder has to solve the problem by making their development machine as stark and drear as the build machine, which inspires one to ask: Why did the coder tart up their machine? Most likely, the developer updated their libraries, either to the most recent version (so the build machine needs and update) or to a beta version (so the developer needs to Not Do That Anymore).

• Plan and confirm updates to software and libraries across the whole development team, and don’t forget the build machines and the occasional coders (e.g. managers).
• Name and version your internal libraries like you were selling and supporting them, because you will do the latter no matter what.
• Embed as much application and library version information into your application’s bug reporting protocol (you do have one, right?) as you can.

Defect Status Translations

Other Terminology