Platinum Partner
ria,flex & air,flex 3

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

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.

Requirements

In order to make the most of this article, you need the following software:

Flex Builder 3


 

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.

Prerequisites

Previous Flex experience is not mandatory for this article. However, some previous application development experience will be helpful.

Using workspaces for project organization

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

checkmarkUse workspaces to keep your Flex projects organized.

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.

checkmarkUse a common directory for your Flex workspace in team environments.

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:

checkmarkFollow common naming conventions for Flex project names.

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:

checkmarkDetermine your target platform.

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:

checkmarkStick with the default "bin-debug" directory unless your Flex project uses a local development server.

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:

checkmarkAlways place source code in a directory named "src".

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:

checkmarkUse a source code control solution for your "Main source" folder.

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:

checkmarkShared SWC libraries should be referenced using the Flex Library path.

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.

checkmarkUse the libs folder to bundle SWC libraries with your Flex project.

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.

checkmarkUse UpperCamelCasing for MXML file names.

checkmarkUse UpperCamelCasing for ActionScript class file names.

checkmarkUse UpperCamelCasing for ActionScript interface file names, and begin the file name with a capitalized letter I.

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.

checkmarkDo not use spaces when naming files!

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

checkmarkDo not use special characters when naming files.

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.

checkmarkDo not use acronyms or abbreviations.

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

checkmarkDo not use periods.

Using packages for code organization

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

checkmarkUse packages to organize and structure your projects codebase.

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:

checkmarkUse lowerCamelCase.

For example: com.seantheflexguy.stringUtils

checkmarkBegin the package name with the top-level domain (TLD) of the application's owner:

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:

checkmarkUse workspaces to keep your Flex projects organized.

checkmarkUse a common directory for your Flex workspace in team environments.

checkmarkFollow common naming conventions for Flex project names.

checkmarkDetermine your target platform.

checkmarkUse the default "bin-debug" directory.

checkmarkPut your code in the "src" directory.

checkmarkUse object-oriented programming practices for Flex projects.

checkmarkUse a source code control solution.

checkmarkReference shared SWC libraries using the Flex Library path.

checkmarkUse the libs folder to bundle SWC libraries with your Flex project.

checkmarkUse UpperCamelCasing for MXML file names.

checkmarkUse UpperCamelCasing for ActionScript Class file names.

checkmarkUse UpperCamelCasing for ActionScript Interface file names, and begin the file name with a capitalized letter I.

checkmarkDo not use spaces when naming files!

checkmarkDo not use special characters when naming files.

checkmarkDo not use acronyms or abbreviations.

checkmarkDo not use periods in file names.

checkmarkUse packages to organize and structure your projects codebase.

checkmarkUse the following format for package names: com.seantheflexguy.stringUtils

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, which will be published on DZone in the coming weeks.


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.

Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 Unported License.

{{ tag }}, {{tag}},

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}
{{ parent.authors[0].realName || parent.author}}

{{ parent.authors[0].tagline || parent.tagline }}

{{ parent.views }} ViewsClicks
Tweet

{{parent.nComments}}