I came across this article (six ways to write more comprehensible code) while reading the BigSpaceShip Blog. It is definitely a good read for Flash developers as I have seen my fair share of Flash designers claim to be “developers” and write absolutely unmaintainable code.

So I thought I would take the IBM article and apply it specifically for Flash actionscript coding:

1. Comments

Taken from point #1 from the IBM article:

Comment your code. Obviously. If you write a procedure, fail to comment it, and return to it a few months later to rework it (and you will), not having comments will cost you time. And time is your most valuable resource. Lost time can’t ever be replaced.

But commenting, like anything else, is a skill. You get better with practice. There is good commenting, and there is bad commenting.

You don’t want to write too much. Suppose you write comments for a function that, in the future, saves you ten minutes of time understanding your code. Great. But suppose your comments are so verbose that it takes five minutes to write them and then, later, five minutes to read them. Then you’ve saved yourself zero time. Not so good.

You don’t want to write too little, either. If code goes on for a page or two without something breaking down what’s going on, well, I hope that code is clear as crystal, because otherwise you’re wasting future time.

The only thing I would add to it is you can minimize the use of comments by making the code self-documenting by appropriate name choices and an explicit logical structure. i.e. a Function named “getCurrentDate” needs no comment whereas “doDate” would probably need some explanation on what the function actually does

2. Constants and Variables

Similar to point #2 in the article, I highly recommend clearly defining and differentiating variables and constants. Our naming convention has always been if it’s a constant, use all caps, i.e. nSCORE (a constant named score which is a number), whereas if it’s a public variable, nScore. To take it further, declare all the constants in one place, don’t do it within the functions, but in the Class Variable Definition. i.e.

class SomeClass {

public var nSCORE:Number= 100

….

}

3. Intuitive Naming Convention

From the article:

The overall objective is simple: write code so that, if someone who has no idea what it’s doing reads it, he or she can understand what’s going on as quickly as possible.

One key strategy for achieving this goal is to give your variables, procedures, etc. good, descriptive names. If someone looks a variable name and goes, “Yeah, I see what that is,” that saves five minutes of searching through the program looking for clues to what the heck incremeter_side_blerfm is supposed to mean.

Look for a good middle balance here. Give things names that are long and clear enough that you understand what they are, but not so long and awkward that they make the code less readable.

A couple naming convention techniques we have been using are:

• Private class variables should have _ + type prefix (_nDepth, means it’s a private variable that is a number, whereas sName is a public variable that is a string)
• Names representing methods/functions must be verbs and written in mixed case starting with lower case (getName(), doRollOver(), etc.)
• All variable declarations should be followed by datatype (private var _nDepth:Number)

4. Do Error Checking

In addition to adding trace() for proper debugging, it’s probably a good idea to implement some error checking into the function. And taken from point #4 from the article, say for example, you have this function

private function addScore(nScore:Number):Number{

return (nScore++);

}

So what if someone mistakenly pass a negative number into the function? It might not be a big deal depending on the application but since the function is called “addScore”, it would probably be confusing if nScore is a negative number.

private function addScore(nScore:Number):Number{

if(nScore>0){

return (nScore++);

}

else{

trace(”Error: Score must be a positive integer”)

}

}

5. “Premature optimization is the root of all evil.” - Donald Knuth

Straight from the article:

Write something that is clean and works. You have all the time in the world to ugly it up with optimization later. But don’t do it until you’re sure that you’re doing the right thing.

6. Don’t be too clever by half.

This to me is the most interesting of all of the advices given in that article. Sometimes I would write ten line of codes for a function but then go back and realize I can optimize it and make it only one line. Only to find out later when a client requests a change, realized I jumped the gun and would have been easier for me to make the change if I retained all ten lines.