Flex best practices – Part 1: Setting up your Flex project

Additional Requirements

Flex 3 SDK (free with a trial of Flex Builder 3)

• Download

If you are willing to sacrifice the powerful tool set provided by Flex Builder 3.0 standalone or plug-in, applications can be developed using only the Flex 3 SDK.

The practices covered in this article should be followed regardless of which setup you use.

This is the first part of my series on using and applying best practices to your Flex development process. This article will focus on best practices for setting up your Flex project.

Why follow best practices? During your Flex development career, your hands will touch many projects. Not all projects will be created from scratch. More than likely you will be working on an established codebase that has been built up over time by different developers working in different stages of their careers. You will be facing projects that may have already begun or have already been released and now need to be refactored, changed, and updated. Time and time again, you will find yourself being thrown into the middle of the development process for various projects. Because of this, it is critical that the project has been started using best practices. Otherwise, you will be spending additional time making sense of the project and understanding the codebase rather than making the requested improvements or changes. This additional time can increase the cost of a project and dramatically detract from the task at hand. For these reasons, the Flex development community has established a set of common best practices for Flex developers to use. Following these best practices improves the clarity of a Flex project and enables Flex developers to focus on innovation rather than learning a myriad of nonstandard development approaches.

Whether you are a contractor or an employee, these best practices will serve as a set of rules and your roadmap to navigating a project's structure, organization, and code format. This article explores common techniques and conventions adopted and used throughout the Flex development community.

Please note that the techniques and practices outlined in this article should be used and adopted where they make sense and clarify the development process for you and your team.

Using workspaces for project organization

Follow the best practices below to use workspaces to organize your Flex projects:

A Flex workspace is basically just a directory on your computer that stores a collection of Flex projects. Workspaces are a good way to organize multiple Flex projects. If this is your first Flex project, I recommend using the default workspace, at least until you are comfortable with what a workspace is and how it relates to your computer's filesystem. A common issue that can arise for beginners when the workspace is changed is that the project files can become difficult to locate. The location can always be found within Flex Builder, but if you're not sure where to look or what a workspace is, questions can surface. As you mature as a developer, you will be held responsible for the management of multiple Flex projects. Setting up a fresh workspace for each project may be the best approach to reducing clutter and enabling you to focus on one project at a time. Be aware that Eclipse preferences are often stored in the workspace, so key bindings need to be set for each workspace; and that can be frustrating if you stray from defaults.

Be sure to note the locations where Flex is storing your project files. The default Flex Builder 3.0 workspace locations are:

Windows XP: C:\Documents and Settings\<User Name>\My Documents\Flex Builder 3

Mac OS X: /Users/<User Name>/Documents/Flex Builder 3

Linux: ~/workspace

To find more information regarding Eclipse workspaces, see Setting the Workspace.

A Flex workspace is unique to each computer on which Flex Builder has been installed. Therefore, each developer can have her own workspace defined. To keep things clear for a team of developers, it is probably a good idea to agree on one workspace, or at least agree on a top-level directory in which to store the multiple workspaces. An example is:

C:\_adobe\workspace

The reason this can be helpful is that everyone will immediately know where to look to find your Flex workspaces or projects, depending on the granularity that you have chosen for your development process. This is a simple thing to do that saves me from having to refer to the Flex Builder workspace settings to figure out where a particular developer stores her files.

Naming conventions for Flex projects

Follow the best practices below on naming conventions for your Flex projects:

For Flex project names, you should always begin with a capital letter, and each subsequent word should also be capitalized. This is called "UpperCamelCase". An example name would be "MyGreatFlexApplication". This is also the name that Flex Builder will use for the application's main deployable MXML file. Note: the Flex project name can be changed at any later point in time.

Determining the application type

Follow the best practices below on determining the application type:

Flex applications can target the Flash Player, which will run in a web browser or the Adobe Integrated Runtime (AIR). When you create Flex projects, you will be prompted to set the application type. This can enable you to set up the project to target the web browser or AIR and minimize the amount of potential re-work that could be required later if you decide to add or change the target platform.

If you do wish to target both the desktop (AIR) and the web browser, additional information can be found in Todd Prekaski's article Building Flex and Adobe AIR applications from the same code base.

Setting the Flex project output

Follow the best practices below on setting the Flex project output:

When Flex projects are compiled, the files that comprise the application are created and written to the Flex project's output directory, called "bin-debug". If you are new to Flex, I recommend using the default "bin-debug" directory to eliminate confusion. However, this is another area where you should check with your organization's standards. If your team is using another output directory, you should follow the preexisting best practices.

If your Flex project uses a local development server, you will need to define the path during the project creation process.

When you are ready to deploy your application using "Export Release Build...", Flex Builder 3.0 will create a new output directory. The default name will be "bin-release".

In review, the output directory will be:

• For development: "bin-debug"
• For deployment: "bin-release"

Managing the source code directory

Follow the best practices below on managing the source code directory:

This is a far-reaching standard that is shared by developers of different backgrounds and languages. Most developers will know to look here for your code. This is the default value provided by Flex Builder 3.0, and I recommend you leave it.

Use object-oriented programming practices for Flex projects.

You will see more detailed standards for working with packages later in this article. For now, keep in mind that following OOP practices is fundamental to Flex application development.

Considering source control management

Follow the best practices below on considering source control management:

Source control management (SCM) is critical in team environments. Source control will enable your team to track changes being made to your application's codebase. Source control gives your team the ability to step forward and backward through a file's history. It is absolutely recommended for your Flex projects. Three common source control solutions are Subversion, CVS and Perforce.

Adding and managing SWC libraries

There are two considerations when deciding which best practice to follow when you are referencing SWC files:

This approach is useful if the SWC library is going to be updated often or is going to be used across multiple projects. To share an SWC library, it needs to be referenced using the Flex Library path.

An advantage to using the libs folder is that there are no external dependencies tied to your application. To compile and run, you will not need to modify the Flex project properties. You should note that the libs directory is automatically added in the Flex project's Library path.

An important thing to remember is that SWC files in the libs folder are usually not automatically updated. SWCs are typically developed separately from your application, so the directory where the SWC is compiled is typically not your Flex project's libs directory.

Working with filenames

Below are several practices you can use to standardize the naming conventions used within your Flex projects.

This indicates that the file is an interface and not a class. Note: this is one practice that has some stigma attached to it. Go with what you find makes sense and then document, communicate, and follow that standard.

This can lead to problems all around, and especially on the Mac.

Such characters as an exclamation mark "!", right square bracket "[" or left parenthesis "(" can be illegal in many contexts and cause severe issues for your application.

An exception to this practice is if the acronym is more commonly used; for example, HTTP, WWW, SQL, and other such acronyms.

Using packages for code organization

Follow the best practices below on using packages for code organization:

Packages are the standard for OOP-based applications. Packages represent logical groupings of related ActionScript and MXML files in the form of classes. The use of packages and classes is fundamental to object-oriented programming.

To continue with community standards, use the following practices for naming your packages:

For example: com.seantheflexguy.stringUtils

for example, com, net, us;

then use the application owner's name:

for example: seantheflexguy, adobe;

then the project name:

for example: burrow;

then the logical grouping of related code files:

for example: utils, components, or whatever is appropriate.

Here's an example of a package name using this convention:

com.seantheflexguy.burrow.view

Flex project setup considerations review

You have seen some somewhat basic practices that, when followed, can foster a clean and understandable working environment for your Flex project. Consistency is a crucial element in understanding another developer's work. As applications mature, different developers can be called upon to modify and scale the app. During this time, a project's codebase shifts in an organic, lifelike way. This is due to the hands and minds of the multiple developers that contribute to the growth of the project. If a set of best practices is used from the beginning, there is a template to show the developers how to structure and format their work.

These practices can be applied to all of your Flex applications. Take a moment to review these practices:

Where to go from here

For more information on using and applying best practices for your Flex development process be sure to see the second part of this article, coming to the Adobe Flex Developer Center soon.

• Adobe Flex coding guidelines
• Flex SDK coding conventions and best practices
• Best Practices for developing with ActionScript 3.0 by Peter Elst - Videos

Disclaimer

Here is a quote that you should keep in mind while you are going through the material presented in this article. I think this quote is pretty applicable:

"Every project targeting Flex is different, and thus best practices vary depending on the team involved and the project at hand. I have seen all manner of project practices that work for small teams but fail for larger teams and vice versa. This is my take on Flex best practices from having looked at many projects over the past three years. In many ways, my recommendations should not come as a surprise, as these are tenets of classical software development." - Ted Patrick

Attributions

Thank you very much to the following people for their input and review of this article. It would not exist without their help: Hong Qiu, Dolores Joya, Eric Feminella, Jeffry Houser, Jesse Warden, Shannon Hicks, and Chris Griffith.