As my commitment to community I’m releasing, with DClick support, our Adobe Flex Coding Guidelines, a document about Flex (MXML and ActionScript) coding conventions that we use on a regular basis.

The objective is clear: provide a common and consistent language to help code comprehension between developers. The practices established in this document are based on Java conventions, Flex 2 SDK and DClick team experience (including myself).

By releasing this document, the idea is to help the community improve their Flex code by using coding conventions as well and hear feedback
from community to continuously improve this document, that by now is a community asset.

I’ll be happy to have volunteers to form a committee or something to evolve this project further.

page 8:
“and dont put a space between the parentheses and the methods arguments?”
it’s silly to enforce someone to not do like that. Putting space there sometimes improves readability, and it should be judged individually.

page 20:
“Code lines must not exceed 100 characters .”
This is another silly sentence. Should developers measure it? No, they will follow breaklines paragraph

And there’s too much “must” word instead of “should”, but maybe it’s just me.
Anyway – it’s good guide, and with some improvements it’ll be great.

One thing I don’t agree with is the declaration of a variable in the for loop:

for (var item:String in something)

Variables should not be declared at random points in the code, but at the top. Otherwise you could end up with a duplicate declaration in your method. The compiler will catch it, but why set yourself up for that?

Duplicate declarations really could be catched by compiler Martin Fowler, in his book Refactoring, suggest to remove unnecessary local variables, e.g. use this:

for (var i:int = 0; i < months.length; i++) { … }

instead of:

var i:int;
for (i = 0; i < months.length; i++) { … }

Also, by keeping the variables declarations close to their uses, we’re aiming to reduce variables “life time” (Steve McConnels’s Code Complete) and making the code more readable: fewer lines to keep in mind at once, keeping and grouping related code in only one screen, reducing the chance to incorrectly change a variable, etc. This is what the Principle of Proximity targets for.

And, besides that ActionScript allows it, in Java, for example, it isn’t allowed. The variable scope is inside the for only, i.e., the variable will not exist outside the for loop.

About page 7: I’m pretty sure it isn’t wrong. However we’re targeting for readability by placing only one declaration per line.

About page 8: The document tells about white space and readability in specific cases. By convention, we’ve chosen to not use spaces in this case. The main reason is that we don’t put a space between the parentheses and its inside content in our normal language. Example: “(like this content)” instead of “( like this content )”.

About page 20: This might be silly, but Eclipse tells what’s the cursor position in the status bar and allows to show the print margin. In this case we’re trying to avoid developers to horizontally scrolls the editor and change editor size everytime.

There’s no right or wrong on coding guidelines. There are conventions.

With regard to placing the declarations inside the for loop: What if you have multiple for loops in your method? Do you declare a different variable for each? Isn’t that unnecessary?

Also, if your method is so large that you must keep variables close to where they are used, you should probably think about refactoring your code. If your methods are so large, aren’t you making it harder to read/follow? Isn’t that worse than where the variables are declared?

Lets say you create a method and keep the declarations next to the functionality where they are used. Then, lets say you copy a section of that code higher up into your method. If you forget to move the declaration and/or change the vars, will it work? Maybe, maybe not. But it will compile just fine. Part of the convention, which I agree with, is to assign a default value when declaring variables. In this scenario it could cause you grief, if your expected default isn’t the default of the type.

For instance:
var b:Number = 1;
b *= a;

var a:Number = 4;
var c:Number = 1;
c *= a;

What is the value of b? c? NaN and 4, respectively.

Obviously, this is a simple example, but in a more complex situation it could be a while before you figure out what the heck is going on.

I don’t think readability should come before practicality.

As to what inou said about page 20, I saw this and thought it seemed like quite a random number. Where does 100 come from? On the same page you mention 80 characters for an A4 print. THAT is something I would get behind. The statement about resolution and percentage of workarea seemed very odd. Why not use something that is standard, like the A4 print area, instead of how big your resolution might be? If you make it adhere to a print standard, then it means you can print anyone’s (that follows the convention) code out and see what you see on the screen, instead of having it wrap in different places because you wrapped at 100 instead of 80.

> Quote: Do you declare a different variable for each? Isn’t that unnecessary?

I think this is developer’s, case by case, decision: create a new variable for the new loop or reuse the same variable by reinitializing its value. We haven’t standardized such thing yet in AS3.

> Quote: If your methods are so large, aren’t you making it harder to read/follow?

Of course. Large methods should be avoided. Anyway we internally follow the principle of proximity and advocates keeping related code close. And, as I previously compared, one screen (about 40-50 lines of code) isn’t a large method in our concept.

And this isn’t valid only for code inside a method, but for outside too, like a variable managed by a getter and a setter. We won’t declared the variable at the top and place the handle methods somewhere in the code: we put them together.

> Quote: Where does 100 come from?

Our developers use 1280 pixels wide resolutions. So, for us, 100 characters per line is a perfect match for our conventions.

The convention outlined by Fabio is in keeping with the coding convention I’ve seen almost universally in the discussion of conventions. It originates from the fact that in C++ (and C#, and I’m sure many other languages) variables are scoped to their block, not their closure (like AS). So, when you declare a variable for a for loop in the for statement, it’s only in the scope of the for statement. Doing this allows for the compiler to do some very clean optimizations, as well as being a cognitive plus for the programmer (as Fabio outlined regarding proximity).

Unfortunately, AS scopes variables to their closure (function), not their block. This is a bum deal in my book as its a deeply ingrained habit (that makes sense) coming from a C++/C# background. I’m not sure whether that’s ECMAScript policy or an ActionScript one, but at the end of the day its really just a compiler issue… the bytecode is agnostic to the issue.

In fact, I’ve been tempted to simply disable the multiple declarations warning and just continue as I do in other languages… I prefer the way the code looks! But I’ve not brought myself to disable the warning yet…

I am really impressed with your writing skills and also with the layout on your weblog. Is this a paid theme or did you customize it yourself? Anyway keep up the excellent quality writing, it is rare to see a great blog like this one today..