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
....
}
(more...)
