Developer Resources

Great news! I hope to be posting again daily.

This time from my new blog and it's all about helping web developers. I have been collecting helpful links from around the web and I will be sharing these with everyone.

Many more posts to come on the new site so check back often.

http://qwick.wordpress.com/

The Downfalls of Flex

I know I've been saying Flex all over the office and stating how great it is and how it makes some things so easy... But there are problems with it.

States - Great or Not?

The mx:State tag is very nice for grouping changes to a screen and applying effects easily. I only have a few issues with the implementation of this.

1) It caches the last time the user navigated there. Ok - not too bad you say. This could be a good thing right? Well, yes and no. If you are building a static screen that won't change again in your program then sure, it's great. If you know exactly what you are going to display, it works fine. The problem is: you won't get startup events again and you can't "reset" the state to clear out this "cache".

This makes dynamic applications difficult to write. How? Well I need to know how many options I can display on a screen so I can split it up into multiple screens (no scroll bars). I need to know how large the area is that I can draw in so I can create multiple screens which have an equal number of options in each. Getting this to work the first time was a bit of a pain... but getting it to work the second time (with different options) required a lot of frustrating work. You may be thinking of solutions - trust me it was difficult and not obvious to implement what I was working on.

2) States are in the same mxml file and share the same code. Yes, you can write components for all of your screens and place them in a ViewStack but, well it has the same problem. You would have to remove the screen each time if you wanted to ensure it would get properly recreated. (and having multiple applications isn't a viable solution).

Solution?

You could create a wrapper for the ViewStack, or create your own State class called Screen - why did this not come bundled? Or you do what the rest of the world does and write a lot of ActionScript rather than mxml so you can control startup/shutdown code, events, etc. Blah.

Waiting for JavaFX may not be the solution you are looking for either -- I know it's different than Flex but, like most things written in Java, it's very sophisticated and probably will not have these types of problems.

Other Issues

Most of the issues I've had all stem from States and their inability to re-dispatch events and re-apply "overrides". This causes a lot of confusion for traditional developers who work with screens. Creating components for each screen doesn't work well if you require other things to change (such as a title bar which is shared with all other components - yes, you can duplicate it in each, but that's not the OO way and doesn't leverage any of the powers of flex such as applying common transitions to some but not all elements.)

Oh ya.. and I want at least a dozen Adobe made themes to come bundled with Flex Builder. Why am I paying money for eclipse to edit mxml? Oh, right, it has better code completion than Flash and FlashDevelop.

I like states - I just want a flag on them that says "re-apply every time it's used". It would also be nice to have them in a separate file (1 per state) if desired. This way, the main mxml file would be quite small. This other file should be able to contain event handlers for the state as well.

I may be able to come up with a solution but I shouldn't have to. This is a very obvious oversight on Adobe's part. I suppose most RIAs are quite static (even though they don't appear to be) but I have situations where I have to produce an application which is different in each install without re-writing it every time.

Please post my oversights below. =)

Get/Set in ActionScript 3 Explained

Introduction

If you have seen ActionScript 3 in Flash CS3 or Flex 2, you may have noticed the get and set statements. Correctly written, these statements follow this format (minus ASDoc comments and bindable metadata tags):

public function get name():String {
return _name;
}

public function set name(value:String):void {
_name = value;
}

Note that the private class variable is _name. This is a standard for get/set methods and somewhat a standard for any private variable in Flex. The underscore (_) is required because the functions are named the same as the variable and the compiler (and those viewing the code) would be confused as to which was being referenced.

Naming the set parameter "value" is a common practice and works well when renaming variables.


What Do get/set Offer?

They act as if the class had a public variable but allow you to do more. If this is to be a read-only property, simply provide only the get function. If this is to be a write-only property (rare), simply provide only the set function. You may also write code to do additional work such as log something, check permissions, set a different variable, or do extra business logic.


ASDoc get Methods

It is a little odd to ASDoc these methods. Remember Get methods should come before set methods. The get should be documented with a short explanation of what the variable represents.

/**
* The first name provided by the credit card
*/
private function get firstName():String {
return _firstName;
}

Remember, just like in Java, documentation of the "firstName" property of the "Person" class shouldn't say "The first name of the person". Offer something more to the reader. Where could the first name come from (credit card, typed by person, typed by customer service agent, parsed from fullName)? What letters could it contain? Could a middle initial exist here?


ASDoc set Methods

Documenting the set methods is a little different. Since the meaning of the variable was explained in the get, it does not need to be repeated in the set. To accomplish this, mark the set as private in the ASDoc.

/**
* @private
*/
private function set firstName(value:String):void {
_firstName = value;
}

This will produce one comment in the generated documentation.

See the livedocs reference for more information:

http://livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Book_Parts&file=asdoc_127_9.html


Bindable get/set Methods

Normally, I mark the class as Bindable so all get/set methods are marked as bindable. It does so with an event named "variableChange" where variable is the get/set method name. Simply putting [Bindable] just above your class definition will accomplish this.

If you need more control, you may write the following at the top of your get method (assuming this is the firstName property):

[Bindable(event="firstNameChange")]

This works the same for public variables. See livedocs for more information:

http://livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Book_Parts&file=asdoc_127_9.html


In Other Languages

Java uses getFirstName() and setFirstName() functions which can be generated by NetBeans using the "refactor" option (also has a keyboard shortcut). They don't name the private variables differently because there is no need. The parameter for the setFirstName is typically the same as the private variable and is assigned by stating: this.firstName = firstName;

VB6 had the get/set functionality in the form of: public property let, public property set, and public property get. Where let was by value and set was by reference (for Objects).

I'm sure there are plenty of other implementations.


My 2 Cents

I use these for every private variable; however, it is much easier to have a public variable and change it to private scope and write get/set functions later if you ever need to do more processing or if you like the ASDoc output better. This does not change the API for the class and allows it to be written much faster.

I like the Flex method the best for simple getters/setters; however, if the function does more work than meets the eye, it should be written as normal get/set methods. This allows you to provide more parameters and alerts users of the class that it may do some additional processing.

Flex Coding Guidelines

Flex Coding Guidelines

I found this great document about flex coding guidelines that one company uses. It is perfect and very much like Java coding conventions.

http://blog.dclick.com.br/2007/02/13/adobe_flex_coding_guidelines_english/

Most of this stuff should be enforced by the compiler (in my opinion) in every language. I know it's strict, but it makes everything so much easier to read and work with. I advise that this become a standard in every company writing in Flex no matter how big or small.


ASDoc Guidelines

If you haven't heard about ASDoc yet, it's a lot like JavaDoc which produces a nice web API reference for all classes and methods. This document describes how to properly write ASDoc comments in your classes.

http://flexed.wordpress.com/2007/01/05/action-script-comment-guidelines/

This site may also be helpful. It mentions tags that I didn't see in Adobe's documentation (such as author) -- but maybe I missed that one. I haven't tried it yet.

http://unleashing.wordpress.com/2007/01/05/action-script-comment-guidelines/


Using ASDoc

The method I have used is to write a batch file (or shell script) that executes the asdoc.exe file from the bin folder with my command line arguments.

Default location in Windows is:
C:\Program Files\Adobe\Flex Builder 2 Plug-in\Flex SDK 2\bin\asdoc.exe

More information on command line arguments and ASDoc usage:

http://livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Book_Parts&file=asdoc_127_9.html

http://labs.adobe.com/wiki/index.php/ASDoc:Using_ASDoc


Flex ActionScript Editor (free)

I haven't written anything using this tool but I have downloaded and installed it. I was very impressed. Could be a good tool if you were writing a bunch of ActionScript classes and didn't like only seeing 4 or so tabs in Flex Builder.

http://www.flashdevelop.org/community/viewtopic.php?t=1001