Advanced Flash Tactics or AFTs are techniques that come from deep within the Flash Art Of War, the oldest Flash military treatise in the world. In this AFT I will go over - 5 Tips for Documenting Code. Documenting code is not high on many people's lists of things to do. Most of the time it is boring, repetitive, and time consuming. If you want to get better at documenting your own code then this is the post for you. I have 5 simple tips to follow while coding to make the process easier.

Tip 1: Automate Code Documentation

Use ANT to do build out your ASDocs. ANT is easy to automate and it allows you an incredible amount of control over how your final documentation gets generated. Here is an example ANT task to run

<target name="asDocs" description="Run the ASDoc executable and generate the ASDocs to the new output folder">

        <exec executable="${FLEX_HOME}/bin/asdoc" failonerror="true">

                <arg line="-doc-sources ${basedir}/src" />

                <arg value="-window-title" />
                <arg value="'ASDoc Title'" />

                <arg value="-output" />
                <arg value="${basedir}/docs" />

        </exec>

        <echo>Docs were created</echo>

</target>

The above Ant task will probably need to be configured for your setup, but hopefully it gives you an idea of how this should work. To see a more advanced setup, check out my build file for Flash Camo. In my own ANT build, I auto generate my documentation the after that, I tell ANT to copy over additional html files along with their assets so that when you read Flash Camo's documentation you will see an introduction to the framework. Here is what the final output looks like - Flash Camo's ASDocs. As you can see I overwrite the default ASDoc page with my own introduction. This is easy to do and something I suggest setting up in your own project.

The final thing I want to say about automation is that you should have it run after all of your builds. Since I am using ANT to generate my swcs or create my swf and load up the browser, having ANT call my ASDoc target after a successful compile is a great way to make sure my documentation is always up to date.

Tip 2: Add Comment Blocks As You Work

There is no secret to this tip, every time you create a new method, add a comment block above it. If you are in Flex Builder there is a great shortcut to add a comment block (command shift d on a mac) that includes room for a description, params and a return if you have one. If you don't want ASDoc to include the method, this is also a good time to add a @private tag to the comment block. Here are a few of the JavaDoc style tags I use - ASDoc Tags.

Tip 3: Focus On Public Methods

When it comes to documenting your methods, spend more time on public methods over private. Although all methods should have some kind of notes that describe what they do, public methods make up your class's API and are what other classes will use to interface with. What does that mean? Well a large percentage of the developers who touch your code are only going to be interested what parts they can access, so make those public methods well documented.

Tip 4: Don't Write War And Peace

When it come to writing comments, only write what other developers will need to know. In the past I would write in depth comments detailing what was going on inside of the method and how things worked. Most developers want to get a quick idea of the method's action, possibly and example of how to use it, and what parameters it needs to work. I try to keep my comments under 1 paragraph if I can help it. When it comes to documenting code KISS (Keep It Simple Stupid) is a great motto to keep in the back of your mind.

Tip 5: TODO And FIXME

It's a real shame that FlexBuilder doesn't automatically support displaying these two comment flags in the Eclipse tasks window but still I use them all the time. If you have something that you need to come back to, add a //TODO comment. If you see something broken, add a //FIXME comment above it. I also tend to keep these comments very short. If I need a detailed reminder on what I have to do I usually put it in a regular comment block after the TODO or FIXME comment.

So that covers my 5 simple tips to help you document your code while you work. You may have noticed I really didn't cover inline commenting. I hardly do it and most of the developers I talk to wouldn't read them anyway. Inline comments are really just for you, so write them in complex parts of your application. Things like parsers or large conditional/switch statements that rely on external data are good candidates for inline commenting. Don't let me stop you from doing it but I would rather spend my time on the above rules then on things no one will really see or read. The most important takeaway from this is to document while you are coding. This helps make sure that the idea is fresh in your head you and you will avoid having to go back and do it later.

Read more from Jesse Freeman.