Adobe Flex Coding Guidelines (English version)
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.
This way, comments on this document (including the best practices) are very welcome! Involve yourself at flexcoders thread, or at this post comments.
Adobe Flex Coding Guidelines v1.2 (English).pdf
Adobe Flex Coding Guidelines v1.2 (Portugues).pdf
Popularidade: 100% [?]
20 comentários para “Adobe Flex Coding Guidelines (English version)”
Skimmed through it. Very nice. Almost 99% the same style as myself. Glad to see someone else with good taste. Now, hopefully the rest of the community will pick this up as well. Good work!
Outstanding work Fabio. This is a perfect resource for anyone doing Flex / AS3 development. Thank you very much for sharing it with the Flex community.
I hate starting curly braces on the next line. Argh.
This looks so much better to me:
public function myFunction():void {
doStuff;
}
Hi Rich, thanks for your comment. We’ve used to place curly braces in the same line too, but we preferred to stick with Adobe conventions on this.
nice job, however your guide is too much restriced. Some examples:
page 7:
This
var a:int = 10, b:int = 20, c:int = 30?
isn’t wrong, it’s pretty clear. This is wrong:
var a:int = 10; b:String = “olala”; c:Boolean = false;
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?
All declarations at the top of the method.
The compiler will do this anyhow. For instance:
a = ‘hello’;
trace(a);
var a:String = ‘bye’;
The compiler doesn’t complain and the trace output is “hello”.
Hi Derek, thanks for your comment!
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.
Hi inou, great you find it useful!
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.
Thanks!
Hi Fabio,
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.
Unless 100 comes from a similar source? Any thoughts?
[…] Adobe Flex Coding Guidelines […]
Hi again Derek,
> 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.
Thanks,
Fabio
Muito obrigado
I’ve been working in Flex for a short while and I think these guidelines should be a great help.
Derek,
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…
Troy.
[…] Ver: http://blog.dclick.com.br/2007/02/13/adobe_flex_coding_guidelines_english/ […]
One suggestion: add “Abstract” on class names that represent abstract classes. Example:
public class AbstractAnimal {}
[…] quem ainda não viu,o Fábio Terracini da lista FlexDev fez há um tempo atráz, um Coding GuideLines para a DClick que visa padronizar os códigos MXML e ActionScript. O doc é muito bom, […]
magnificent trees black where I spent most neighborhood probably chunk
thats it, guy
Hello everybody, my name is Damion, and I’m glad to join your conmunity,
and wish to assit as far as possible.
[…] DClick: http://blog.dclick.com.br/2007/02/13/adobe_flex_coding_guidelines_english/ […]
Adicionar comentário
Skimmed through it. Very nice. Almost 99% the same style as myself. Glad to see someone else with good taste. Now, hopefully the rest of the community will pick this up as well. Good work!
Outstanding work Fabio. This is a perfect resource for anyone doing Flex / AS3 development. Thank you very much for sharing it with the Flex community.
I hate starting curly braces on the next line. Argh.
This looks so much better to me:
public function myFunction():void {
doStuff;
}
Hi Rich, thanks for your comment. We’ve used to place curly braces in the same line too, but we preferred to stick with Adobe conventions on this.
nice job, however your guide is too much restriced. Some examples:
page 7:
This
var a:int = 10, b:int = 20, c:int = 30?
isn’t wrong, it’s pretty clear. This is wrong:
var a:int = 10; b:String = “olala”; c:Boolean = false;
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?
All declarations at the top of the method.
The compiler will do this anyhow. For instance:
a = ‘hello’;
trace(a);
var a:String = ‘bye’;
The compiler doesn’t complain and the trace output is “hello”.
Hi Derek, thanks for your comment!
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.
Hi inou, great you find it useful!
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.
Thanks!
Hi Fabio,
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.
Unless 100 comes from a similar source? Any thoughts?
[…] Adobe Flex Coding Guidelines […]
Hi again Derek,
> 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.
Thanks,
Fabio
Muito obrigado
I’ve been working in Flex for a short while and I think these guidelines should be a great help.
Derek,
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…
Troy.
[…] Ver: http://blog.dclick.com.br/2007/02/13/adobe_flex_coding_guidelines_english/ […]
One suggestion: add “Abstract” on class names that represent abstract classes. Example:
public class AbstractAnimal {}
[…] quem ainda não viu,o Fábio Terracini da lista FlexDev fez há um tempo atráz, um Coding GuideLines para a DClick que visa padronizar os códigos MXML e ActionScript. O doc é muito bom, […]
magnificent trees black where I spent most neighborhood probably chunk
thats it, guy
Hello everybody, my name is Damion, and I’m glad to join your conmunity,
and wish to assit as far as possible.
[…] DClick: http://blog.dclick.com.br/2007/02/13/adobe_flex_coding_guidelines_english/ […]
