Six Ways to write more comprehensible Flash ActionScript Code
June 1, 2007 04:37 pm
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_blerfmis 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.
June 3, 2007, 4:16 pm (Comment)
Great advice. I remember hearing that code doesn’t need comments because if the logic is well-formed, the code will be “readable” and self-explanatory. This may be true for some languages, but not with Actionscript. Another good practice that should be on the list is unit testing.
June 19, 2007, 6:46 pm (Comment)
Nice!
July 9, 2007, 3:33 am (Comment)
Cool…
July 9, 2007, 4:24 pm (Comment)
Cool…