Comments on the Flex Best Coding Practices

Adobe recently published preliminary coding guidelines for people making contributions to the Flex framework (mx packages). Here's the link:

Flex SDK coding conventions and best practices

Although it's specifically meant for the Flex project, the vast majority of their guidelines are applicable to ActionScript 3.0 code in general. Overall, I really like their direction. But I thought I'd take some time to comment on what I don't like or find questionable.

1. Acronyms

When using acronyms in code, the programmer faces a dilemma: convert the case to whatever is appropriate for the context, or leave them all in caps? They opt for the latter, and usually this is fine. However, names that use two acronyms can suffer from ambiguity, as in their hypothetical example loadCSSURL (which some programmers would prefer be rendered loadCssUrl).

Personally, I think there's no good solution here, so I just go with their approach. But I recognize that this approach has problems. As they say about loadCSSURL, "[T]ry to avoid such names."

2. Package names should always be nouns or gerunds

Actually, guys, a gerund is a noun. You're thinking of participles, which are verbs and, in English, look exactly like gerunds. (Gerund: "Walking is fun." Participle: "I was walking.")

Anyway, I don't see why this should be so. I've named a lot of packages after verbs, myself. Is it really that bad to name a package of things that draw something draw as opposed to drawers or drawing?

3. Start interface names with "I"

I've gone back and forth on this one and have finally decided that I actually hate it. Suppose I start out making something an abstract class and then later decide it should be an interface (or vice versa)? Why should I have to rename it when, to external code, nothing has changed? In most cases, external code shouldn't care whether an entity is an interface or a class (the obvious exception being when external code is expected to implement the interface).

I tend to use adjective for interfaces when possible, but often I just use plain old nouns. What's the harm?

4. Brackets on their own lines

They never explicitly recommend this, but all the examples show it. To illustrate what I mean, they recommend this:

function foo():void
{
    if (test())
    {
        doSomething();
        doSomethingElse();
    }
    else
    {
        doAnotherThing();
    }
}

Over this:

function foo():void {
    if (test()) {
        doSomething();
        doSomethingElse();
    } else {
        doAnotherThing();
    }
}

Now I've heard people swear by the former, saying it makes blocks of code much easier to spot. But to me, it seems like a huge waste of space. I can only see so many lines at once, and if half of them are brackets, I'm going to have to be paging up and down an awful lot. Besides, I've been using cradled brackets for over a decade and I don't have any problems spotting blocks.

That said, I've never tried the other way, so I reserve final judgment until I give it a fair chance.

5. Event handler names

The recommend the form eventNameHandler. I like the older ActionScript convention onEventName. Not only is it more succinct, but it has the added benefit of placing all your handlers together when you sort methods alphabetically.

6. Postfix vs. prefix operators

They recommend postfix over prefix operators, despite the fact that prefix operators are generally faster. This completely baffles me. If this:

for (var i:int = 0; i < n; ++i) {
    trace(i);
}

...is faster than this:

for (var i:int = 0; i < n; i++) {
    trace(i);
}

... then why on Earth would you ever use the latter? It's not like one is more readable than the other. They're equally legible, and one is faster—no contest.

7. Single-statement if blocks

They recommend leaving brackets off. Personally, I prefer to always use brackets—it's more visually cohesive, and it makes things easier when you later realize you do need another statement in there, after all.

---

By this time it probably sounds like I hate their ideas, but actually, these are the only ones (and I follow that first one, anyway). Everything else is great and much of it had me going, "Yes! Preach it!"

This is something every ActionScript coder should read. Like me, you may not agree on every detail, but overall, it's an excellent guide.