I love AS3. However after some time working with Javascript, I’ve come to miss the versatility of AS2 dynamic typing. Don’t get me wrong, AS3 strong typing is great, and the compile time errors save tons of debugging hours. But sometimes strong typing can lead to multiple functions that do the same thing, just because one argument type is different.
Some languages, like Java, support multiple method signatures. AS3 doesn’t, but the guys at Adobe do something similar with methods like String.replace, where the last argument can be either a String or a Function. They do it giving the second argument an Object type. Yes, the core Object class. Everybody knows how this class works, but with all the cool features of AS3 we tend to forget it. For example, to emulate the String.replace behavior we can do something like this.
function replace(pattern:*, repl:Object):String{
if(repl is String)
// do something when repl is a String
else if(repl is Function)
// do something when repl is a Function
else
throw(new Error("The second argument of String has to be either a String or a Function"));
}
I don’t remember where I read that using is to test type casting is faster than doing something like…
String(my_string) != null
… is slower than is, I don’t know if it’s true but I do it. Altough is sometimes behaves oddly.
For parameters or options we can also use hasOwnProperty to test if a parameter has been set like this:
function modify_image(img:*, params:Object = null):void{
if(!params) params = {width: 99}; //set default values if no parameters given
else { // verify if the params object has all the necessary parameters for the method to work
if(!params.hasOwnProperty("width")) params.width = 99;
}
// do something
}
Also lets not forget AS’ Javascript inheritance. We can use method closures and the …(rest) parameter (similar to Javascript’s argument variable).
I personally use these kind of techniques with helper or configuration classes. These kind of classes focus on one task and so they are easier to test; unlike interactive components, where more robust code is preferable.
Documenting your Flash IDE project with ASDoc
So, you want to generate some documentation for your project?
I’ve found two great options: NaturalDocs and ASDoc.
NaturalDocs is very nice and it supports a wide variety of languages. However I didn’t like how it documented inherited properties and methods.
I then turned to ASDoc. ASDoc is part of the Flex SDK, and it’s what the big guys at Adobe use.
Documenting Flex projects is “easy”. However there’s not too much documentation around for using ASDoc with the Flash IDE. I had a hard time making it work the first time I tried it, so here’s a list of tips I’d like to share to make your ASDoc experience less painful.
First of all, there’s running the ASDoc command. While you can run the asdoc command through the console, write a shell script or a rake task, I recommend ASDocr. ASDocr gives you a nice GUI to run the command. You just need to point the location of the asdoc command and the sourche path of your project and your are ready to go.
Is very unlikely you’ll succeed the first time. Why? ASDoc fails if it find errors in your code, that includes all of those classes that are not being compiled (and thus the Flash IDE doesn’t wanr you). So take all those files out and try it again.
Second is dependencies. The Flash IDE creates a lot of stuff on the background so you don’t have to care for it. Remember the “A definition for this class could not be found in the classpath, so one will be automatically generated in the SWF file upon export” message? Well, ASDoc will look for those classes but they won’t be on your classpath, so it fails. The solution, create a class for every one of the symbols you export for Actionscript.
You also have to deal with symbols with instance names. Normally you can access these symbols in your class by using the instance name. The Flash IDE creates a property inside your object so the symbol can be fetched from that property. That’s why you can’t have a method and a symbol with the same name/instance. ASDoc doesn’t know about these magic properties and fails. To solve this issue use getChildByName instead.
this.my_symbol_instance_name //change this this.getChildByName("my_symbol_instance_name") //to thisI usually name symbols on the stage with an appended underscore (_my_symbol_instance_name) and save into a private variable (private var my_symbol_instance_name:DisplayObject).
It’s important to know that getChildByName will throw an error if it doesn’t find a symbol, so you’ll want to wrap it inside a try…catch..finally block then.
And finally comes the libraries. ASDoc only recognizes .swc files or directories containing .swc files as the library-path. Use the .swc packaged version of your libraries (if available) or create your own. Creating .swc files with the Flash IDE is a little bit tricky too, take a look here for more information.
I haven’t found any more things preventing my code from bein documented with ASDoc, if you find anything else feel free to comment. I also haven’t been able to run ASDoc with the FLVPlayer component, I use the wildcard so it doesn’t look for the class definition.