Best Practices Checklist
I’ve been asked to test candidates for projects in need of good Flex 2 and AS3 developers for several of my clients now and made a little checklist of things I believe are essential when reviewing their code which I thought I’d share with you guys.
Best practices of course aren’t an exact science but these are some ‘common sense’ approaches I personally look for:
separate the data model from your view(s)
This is absolutely essential, don’t just mix it into your code logic — you want to have it loosely coupled.use public, private, protected and internal scope properly
Think about encapsulation and don’t just open everything up as public class members for convenience. Access control modifiers were introduced for a reason.architect your application before you start
Make sure you spend some time to draw out your project and get a helicopter view of what it is you are building. There’s nothing worse than having to ‘glue’ on classes as you go along because you hadn’t accomodated a particular feature.event based programming
Do not hardcode sequences of method calls, you want your methods to be self-contained bits of functionality.naming conventions
Use a consistent naming convention throughout the project, make the names of your class properties, methods and arguments self-explanatory and avoid at all cost using names like foo, bar, myWorkaroundMethod etc.commenting your code
Don’t use code commenting to simply explain what your method does (the name itself should ideally tell you enough) but explain how to use it, what arguments to pass what return values to expect. Commenting your code is different from documenting code. If you need more than 5 lines of comments to explain how to use a method you might want to consider rearchitecting it.
While these practices don’t only apply to Flex and AS3 development, without this basis I’ll have difficultly recommending someone for any development job.
I’m planning to write a follow up post in a couple of days explaining what I particularly look for in Flex 2 and AS3 developers and some best practices for streamlining the development process when working in a team.
Anything you would add to this checklist?
This work, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 2.0 Belgium License.
There are some more things, that can be considered in Flex/AS3 context:-
1) Proper packaging structure for MXML and AS3 components, util classes and other libraries are important. Needs to be documented, so that team knows where to find things and not to duplicate things if it exists already. Saves loads of time over the time..
2) It’s good idea to come up convention to give ids to MXML tags and a guidelines so that designers (using FlexBuilder) follow that.
3) If #2 is followed consistently, it would allow to keep AS code in include file instead of MXML, this avoids any kind of mishaps in code if MXML is changed (layout etc) by someone else. I agree, version-control saves you from that…but having code outside gives you more control over things in terms of Version-Control
4) For a big team, it makes sense to create templates for different things (AS3 components, MXML components, Modules etc). This allows to quickly create things from templates without including the namespaces, includes etc…
Thanks Peter for posting this, this got me thinking about the practices…I would think more realistic and practical things and update here
-abdul
Some great additions Abdul — absolutely agree there!
I generally also recommend using TODO, FIXME notes in the code with the developers initials and references to a bug id for team projects.
Also worth writing interfaces for any generic base classes that are used throughout multiple projects. Just helps in narrowing down any possibly issues and makes sure you have a solid implementation.
Will probably think of some more, its a really good exercise to consider these things even if you don’t end up using every single best practice.
Commenting is actually the one area that I think most developers need improvement in the most. It’s frustrating to me when I pop open a class file only to find that each method has a massive paragraph of Javadoc-ready commenting. Beyond the fact that the method’s commenting and documentation are the same thing, the developers that comment like that also tend to neglect the code inside the method itself. To me, a good commenting practice is to pretend like you are writing and commenting code for somebody that is learning the language. Not only will the developers that look at your script later on appreciate it, but months down the road when you have to revisit it for whatever reason, you will certainly thank yourself as well.
Documentation -> How and why you use it.
Commenting -> How and why it works.
Great post though; I definitely agree with each of those practices.
Thanks for the tips guys. This really helps.
Ryan: “…a good commenting practice is to pretend like you are writing and commenting code for somebody that is learning the language.”
I couldn’t agree more. I try to follow this approach for code that I post online. For code at work I comment for my own elucidation and that’s about it. I should really get better at that.
By the way, one of the funniest comments I ever read was from a dev that left before I started working at Xbox. It basically said, “All this code is crap. If you need to make changes to this project then just start over. It will save time.”
I appreciated the honesty.
I’m surprised by Ryan’s and oz’s comments on commenting. I never think I need to teach actionscript. I like to be as precise as poss in putting the odd line in saying whats going on, and when something is not obvious, that’s when commenting is IMO worth a great deal - to both yourself at a later date (5mins or 5days) and everyone else who might have the experience of reading and following your code.
Something I’ve recently started to do is to simply list events dispatched by the class at the top, for example like so:
[Event] onItemAdded {item}
[Event] onItemRemoved {item}
I’ve found this commenting technique really help above everything else I use or have tried.
Peter,
Knowing when and where a comment is necessary is subjective; what’s obvious to you might not be obvious to somebody else. It’s simply a good habit to be in and other programmers will certainly respect you for it.
Comments are really important. These days, documentation is generated from code. It has become generally practice to keep big blocks of comments with all those common comment elements so that documentation team, if you have one, doesn’t have to write everything from scratch rather they focus on description etc.
I believe, such comments doesn’t help much to a developer who is walking through code. Good code (method name, signature, clear responsibility per method/class etc) speaks in itself. Sometimes, developers use tricks/hacks or sometimes code path is different based on context (params, conditions etc) , I like those to be commented (@private ?) for another developer who would deal with code in future. I don’t assume that I would be only person dealing with code. That’s I try to clean up (comment, names etc) code by refactoring to make it easy (formatting, naming-convention, less-use-of-non-standard things or hacks etc) to understand and intuitive to other developers…
Commenting about platform specific hacks/tricks is really useful for developers new to platform (Flash Player etc)…
Abdul, good points — one of the things I hate about auto-generated docs is that it promotes this absurdly long commenting style.
I’ve seen too many projects that try to mimick adobe livedocs for each and every method, resulting in more comments than actual code in a class.
In my view comments are aimed at developers, documentation is a full text description that somebody like your project manager could grasp the jist of
When I talked about those long comment blocks, I meant Flex framework for example
It depends team to team, developer to developer…Sometimes there are different opinions within team so people end up with something workable common…
-abdul