Worst Ever Paragraph in a Technical Doc

I’m working on my Flash game framework. Progress, which I admit is slow, requires a good understanding of the Flash CS4 Component model. I embarked on this project a few weeks ago without realizing 3 things:

  1. The CS4 Component Model is very different from the CS3 model.
  2. There is very little good documentation for CS4 Components.
  3. Flash and CS4 Components have become the step children of Flex and it’s entirely different, incompatible component model.

๐Ÿ™

I’m not sure why the CS3 Component Model had to go. The major change seems to be that CS3 Comps were based on a subclass of MovieClip while CS4 Comps are based on a subclass of Sprite. This change in inheritance has some great technical advantages but even more practical disadvantages.

MovieClip is a heavy weight object with lots of functionality. It’s a great starting point for components because you have all of Flash’s frame-based animation at your command. Sprite is a superclass of MovieClip and hard-coded to a single frame. Sprite is a great idea, since a many elements in a Flash game are static. Using Sprite-based components means less overhead for the Flash engine to grind through. Sprite-based components are less overhead for the programmer too: Since Flash plays any MovieClip by default you don’t need to include frame management code in a CS4 Component.

That’s all good. Here’s the bad:

CS4 Components can not share the same stage with CS3 Components. You have to choose one or the other!

There are 5 less Adobe-authored CS4 Components than CS3. Some of my favorites were not ported to CS4 including Accordion, Tree, and Window. I can still use the original CS3 set of components but not in the same application with CS4 components.

/cry

A quick search of FlashDen lists 236 CS3 components and only 51 CS4 components. This means to me Adobe has been doing a poor job of evangelizing the benefits of CS4 Components or that the benefits aren’t worth the effort. Or, as I suspect, all of the above.

CS4 components can be compiled so that their code is hidden. I hate that. I hope I don’t need to argue the open source model here. But someone at adobe should read the Wikipedia entry. I know developers who want to make money from their Flash components probably demanded this feature. I want to grab these follow capitalists by the shoulders, look them square in the eye, and say “There is a better way!” Look to the Perl community! Look to the Ruby community! Look to the PHP community! None of our brothers and sisters are starving there! Hiding your code leads to a lack of adoption, a lack of quality, and the illusion that you can sit on your butt and no longer have to innovate.

For me, the single biggest problem with the CS4 component model is the scarcity of quality documentation. The books and sites devoted to CS3 components are too numerous to mention. I found only one decent article on Adobe’s DevNet about CS4 Components: Creating ActionScript 3.0 components in Flash by Jeff Kamerer. It’s a very comprehensive article, points out many of the problematic design details that need to be considered when authoring CS4 components, but it’s rambling and needs much editing.

In fact it contains one of the worst paragraphs I’ve ever read in years of reading technical documentation:

You’ll find ActionScript metadata throughout all component code: in ActionScript 2.0 and ActionScript 3.0, in Flash and in Flex. ActionScript metadata comes between square brackets. It has a name that is followed by a list of name/value pairs enclosed in parentheses. For example, here is metadata with the name Inspectable and a single name/value pair, defaultValue/Label: [Inspectable(defaultValue="Label")]

Confusing yes?

What the author means to say (and I don’t blame him, I blame the nameless Adobe technical editor who should have fixed this) is that metadata is enclosed in square brackets and defined by a name and a string value or a list of key/value pairs. The example given is the most confusing part of this paragraph: It would be much clearer if a general example was used like [Name(key="value")]. By using a specific example he makes us hunt for the general hidden in the details. The example uses “defaultValue” as the key and confuses us with the word “value” on the left (the value is on the right). By using the string “Label” for the value the example confuses us with a synonym for a name on the right (the name, or key, goes on the left).

Unless I’m so confused I got it wrong.