featured_image

  1. Overview of the Refactoring process
  2. Identify and Group your Access Modifiers
  3. Choose Wise Variable Names, Prefixes and Suffixes
  4. Sort each Access Modifier Groups Alphabetically
  5. **View All**

Overview of the Refactoring process


If you have ever worked on a large project (or you are currently), you may have experienced the Janitorial-syndrome, which is “Man, I wish there was a virtual Janitor that could clean this mess!” . To fight off this overwhelming feeling, why not take your own actions to help yourself and the other members of your development team?

Refactoring

This is the process of renaming members, such as, variables, accessors, instance and class methods. In layman’s terms, this is an effort to keep your (and others’) code clean, readable, intuitive and meaningful at first glance. They can also be renamed for practical reasons, such as prefixing all the similar variables that store related values or references of a specific feature (ex: a few getter-methods  to retrieve a list of certain grid types, such as tilesEmpty, tilesOccupied, tilesLocked, tilesNearCharacter).

For the sake of demonstrating the cleanup process in an interesting way, we will be using a portion of a Ship Class for an Asteroid kind of game!

Let’s say you started off with these variables:

public static var shots:Array;
private static const firingInterval:int;
public static const firingSpeed:int;
private var speed:int;
private var shotsfired:int;
private var angle:Number;
private var lives:int;
public var score:int;
private var weapon:Weapon;
public var upgrades:Array;

Yuck! Not very pretty! Let’s give this bit of code a good wash, shall we?

Continue to the next page…

Identify and Group your Access Modifiers

Group each Access Modifiers together

This first step is crucial to make the remaining steps a breeze. By sorting your variables by their access modifiers, you will gain more advantage when it comes to indenting, renaming, and navigating throughout the code using only your keyboard.

public static const firingSpeed:int;
private static const firingInterval:int;

public static var shots:Array;

private var speed:int;
private var shotsfired:int;
private var angle:Number;
private var lives:int;
private var weapon:Weapon;

public var score:int;
public var upgrades:Array;

Identify your Variables and Constants by Access Modifiers

The next step helps to create a contrast between your ‘private’  and ‘public’  variables & constants. This may vary by programming language or company standards, but generally (and preferably) it is a good idea to:

– Prefix private  variables and constants with an underscore ‘_’ .
– Write public  and private  variables in camelCasing .
– Write constants in UPPER_CASE  and separate each words with an underscore ‘_’ .
– Put static  variables and constants at the top of your class.
– Put the static  keyword following after  the access modifiers (should be the second word).

Following the steps above we should arrive to something like this:

public static const FIRING_SPEED:int;
private static const _FIRING_INTERVAL:int;

public static var shots:Array;

private var _speed:int;
private var _shotsFired:int;
private var _angle:Number;
private var _lives:int;
private var _weapon:Weapon;

public var score:int;
public var upgrades:Array;

Following this procedure will greatly improve the distinction between which variables are externally or internally available throughout the Class method bodies.

On the next page, we will see how to make the variable names more practical and more meaningful.

Choose Wise Variable Names, Prefixes and Suffixes

What is the point of coding if you can’t make any sense of the very thing that holds your data? Well, there really isn’t a point. Even though I might of personally done this myself, it drives me nuts to see meaningless variable names used in a function that seems to do a very complex task. I would at least urge everyone to make the member variables (Class and Instance level) self-explanatory and relevant. If you want to go the extra mile, I would encourage people to apply the following rules to the local variables as well:

Boolean (on/off) values should be in the form: is****, has****, can**** , depending on whether it’s about a status , an ownership , or an ability .
Integer values used for counting  certain items should be in the form: num**** , or ****Total  depending on whether you wish to match the prefix of another variable or not.
– Multiple variables or constants pertaining to a similar context should use the same prefix to keep them alphabetically tied together.
variables that refers to a selected object in some manner should be in the form: current****.
variables that hold a collection of objects (Arrays) should be in their plural form, or suffixed with: ****List.

A few extra good naming conventions for specific data-types:

XML variables should be of the form: x**** (ex: xDocument, xElements, xImages).
XML attribute references should be of the form: a**** (ex: aDocumentName, aElementID, aImageURL).
Arguments (or parameters) in a method declaration should be prefixed by: p**** (ex: pFileList, pIsAlive, pCallback).
Dynamic Argument Lists (where any number of parameters can be passed) should simply be: … args, or … pArgs

public static const FIRING_SPEED:int;
private static const _FIRING_INTERVAL:int;

public static var shots:Array;

private var _speed:int;
private var _shotsFiredTotal:int;
private var _angle:Number;
private var _numOfLives:int;
private var _currentWeapon:Weapon;

public var score:int;
public var upgrades:Array;

Now imagine if this had a few more dozen lines of variable declarations. With the steps we have taken so far, it would be more meaningful, yes… but the line-order of your declarations might get you cross-eyed!

Let’s see what we can do to improve the flow of our code.

Sort each Access Modifier Groups Alphabetically

If the modifications are not apparent enough as is, you may need to use one last trick.

Alphabetically Sorting by Groups

If your IDE supports it, give this option a shot to see if it improves the readability of your code.

private static const _FIRING_INTERVAL:int;
public static const FIRING_SPEED:int;

public static var shots:Array;

private var _angle:Number;
private var _currentWeapon:Weapon;
private var _numOfLives:int;
private var _shotsFiredTotal:int;
private var _speed:int;

public var score:int;
public var upgrades:Array;
FlashDevelop supports this – Select the entire groups of variables (including static, constants, private, public, etc.) and choose Edit - Sort Line Groups

With all of the changes that we have done at this point, hopefully you can see a noticeable improvement from when we started!

Conclusion

Mr. Clean

Mr. Clean, approving your work!


In the end, you have to subjectively decide “Have I done enough? Can I re-arrange this any further?” . If you find yourself making minor tweaks, face a brick-wall and undo  those tweaks, this is generally a sign you have done all you could to perfect the code.

When there are no further changes to be made, you will know you are done!

For More Information

These “best practices”  that I share with you in this blog are a sum of all the habits, personal research and company code-standards that I have cultivated over the years. If you want to improve your programming skills, I can’t recommend this book enough:




Clean Code: A Handbook of Agile Software Craftsmanship
by Robert C. Martin 
Amazon link: http://www.amazon.ca/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

Although this book isn’t aimed only for ActionScript 3.0 developers, using the advice of this book will make a huge difference in your code. Your coworkers, and yourself, will thank you for it.

If you have any other suggestions for “Clean Coding” , please share it in the comment form below! :)

  1. Overview of the Refactoring process
  2. Identify and Group your Access Modifiers
  3. Choose Wise Variable Names, Prefixes and Suffixes
  4. Sort each Access Modifier Groups Alphabetically
  5. **View All**