Documenting Your Code for Fun and Profit

-

May 22nd, 2008

by Josh Buhler

When writing code for a project, the developer writing the code has a pretty good idea (usually) of what’s going on in their code. However, there are many times where a new developer is brought on to a project in the middle of development, or is asked to go back and fix some bugs in an older project. There are also several times where the developer who actually wrote the code needs to go back and look at something they wrote days, weeks, or even years ago, and will need to know what’s going on in that project’s code.

As developers working on projects, especially large and complex projects, knowing what’s actually happening when you look at the code for a project is essential. We’ll be talking about how you can work around these issues by writing cleaner, self-documenting code (yes, it’s possible), and how to use some tools to help generate documentation that can easily be referenced by those developers working on a project.

Types of Documentation

• Self-Documenting Code
• Comments
• External Documentation

Self-Documenting Code

Self-documenting code is just that – code that documents itself. The most important concept here is going to be the naming conventions you decide to use throughout your code. Find a naming convention that makes sense, and stick with it. If you use these conventions throughout your code, figuring out what a particular variable or method does is much easier.

Basic Naming Conventions

• _private for private variables
• public for public vars
• button_btn, movieclip_mc, radioBtn_rb, etc.

Above are some examples of some basic naming conventions. If I follow the examples above, anytime I encounter a variable whose name begins with an underscore, I’ll know right away that that variable is private in scope.

What about the third example above? That’s a bit of a holdover from my Flash MX days, assigning instance names to symbols. By adding _mc or _btn to all of my MovieClips or Buttons, I could always know the type of symbol that I was referencing just by looking at it’s instance name. This still applies to Flex – when assigning an id attribute to a MXML tag, if I name things using this convention, I’ll know the types of components I’m referencing just by looking at their names in my ActionScript.

Use Descriptive Names

Look at the names of the symbols in this Flash library. Other than the kind of symbol they are (based on their icons and the “Kind” column), do you have any idea what these symbols are, or what they do? This is an extreme example (and real), but you get the idea. Be smart when naming things, be it variables, components, graphics, methods, etc.

So… what types of things should you avoid?

• Single-letter Variable Names – Avoid them like the plague. They’re ok for loop iterators, but when you’re storing a class variable as ‘k’, what is it supposed to be? If you call your variables a, b, c, then it will be pretty much impossible to search for instances of them using your code editor. Further, nobody will be able to guess what they are for.
• usingRidiculouslyLongVariableAndMethodNames – A descriptive name is one thing, but writing an essay as your variable name is pushing it.

Remember:

“If it looks like a cow and acts like a cow, call it a cow.
Once you call it a cow, make sure you always call it a cow.”

When naming a method, try to describe it’s intent. Use names like “addCustomer()” instead of “add()”.

Also, try to avoid “magic numbers”, meaning numbers that make the code work, but there is no explanation why. If you need to use a specific number for your code to work, store it in a variable with a descriptive name, then reference that variable instead of the number.

Writing self-documenting code isn’t hard, it just requires a bit of dedication.

Links

• Writing Unmaintainable Code
• Self Documenting Code
• Self Documenting Code

Comments

Comment the ever-living-crap out of your code. Don’t go over the top, but at least leave some notes as to what’s going on.

Use the basic rule of “What, how, where, and why“.

What does it do?

Should be self-explanatory. What does this block of code do? Add at least a sentence explaining what the method is supposed to be doing, or what the variable is tracking.

How does it work?

Usually we can figure this out just be reading the code. But if you’re doing something fairly tricky, or that’s not immediately obvious, you might want to clear this up in your comments.

Where are all the pieces?

If your code relies on classes, components, or other libraries that aren’t distributed with the source, you should add comments that explain where to find the pieces you’ll need to actually do anything with the code.

Why did you do it this way?

For example, if you have a for loop that runs through an Array and looks like this:

Will I know why we started at 1, and not 0? Are we skipping the first element on purpose, or was it a mistake? Adding a simple comment to explain why we’re starting at 1 would be a great idea right here.

If there are multiple ways to perform a task, and you choose a method that is a little more obscure, you may want to leave a note explaining why you chose to do it the way that you did.

Also, if you’re doing something that fixes a bug, you should make note of that as well.

Links

• How to document your code

External Documentation

Now for the fun part – creating external documentation that explains what your code does, and how it does it. This documentation can be as simple as an API reference, or as complex as a full book containing use cases, flow charts, sample files, etc.

For many projects, using a tool like Trac can be a great asset, as it can do more than manage tasks and track issues with the project. Trac has an integrated wiki which can easily be used to document various aspects of the project, and can allow you to attach files associated with the project, such as diagrams or design comps.

Creating API references for a project can at first seem like a daunting task, but there are several tools available to help you generate these documents automatically. You provide these tools with the location of your code, and they’ll generate the docs. As mediaRAIN generally works with ActionScript and PHP, I’ve linked to a few of the tools available for generating documentation below for both languages.

Generally, these tools examine your code, and output HTML based on the APIs exposed in your code. With minimal work, you’ll be able to at least get a set of documentation that lists all of the public methods and properties your code provides. This can be very helpful for other developers that will be utilizing your components or libraries.

These tools also allow you to add comments to your code that will be placed in the HTML output, allowing for better explanations of how to use the code. As the methods for documenting your code using these tools varies, you’ll need to read the instructions for each tool that you wish to use.

ActionScript

ASDoc

• Part of the FlexSDK
• AS3 only
• Command-line interface, but can be integrated with Flex Builder, ANT, or other tools
• Using ASDoc

NaturalDocs

• Open-source
• AS3, AS2, PHP, Ruby, JavaScript, and more
• Command-line

VisDoc

• Part of the FlexSDK
• $40
• AS3, AS2

PHP

PHPDoctor

• Open-source

phpDocumentor

• Open-source

NaturalDocs

• Open-source
• AS3, AS2, PHP, Ruby, JavaScript, and more
• Command-line