There is no code that is so good that it couldn’t be any better. I’m far from immune to this, but I am a little OCD about a few things that I think benefit any team collaborating on a project. Some of this is common sense, but occasionally overlooked, for sake of time or whatnot. Most of this is to do with Flash and Haxe development, but could benefit most developers.
Being organized helps you stay organized.
Keeping up with organization as a project progresses enhances your organization structure, and saves everyone time navigating directories or a library. There are often aspects of projects where organization was only passively considered. In early stages of development it may not seem like a problem, but before long it becomes a chore, and less likely to be dealt with. Flash libraries are an example of where this becomes important. If you make a habit of keeping items off the base level of your library, it is easy to visually identify newly created items as they are populated there from Flash. After creating a number of new symbols, you know that everything on the base level is new, related, and likely, can all go together into the same folders.
Remove stuff that’s not needed so people don’t get confused about it later.
When you find an unfamiliar class, asset, or symbol in a program, the obvious thing to do is figure out what it’s for. It might be easy to see that it’s a relic from an old feature that was discarded previously, or it might be quite perplexing. You may end up searching around, wondering if you’re misunderstanding something about how the program works, or worried that a feature was corrupted or deleted unintentionally. Searching around turns up a dead ends. You may decide to clean it out from the project, but you have to be confident about that decision, and that may require following up with the previous developer, and hopefully they’re not out on vacation. When possible, clean up the trail you’ve left behind of unused items, so everyone knows what they are looking at is relevant.
Name Flash library symbols their corresponding class name. Use class naming syntax even if they are not linked to classes.
Whether or not a library symbol is linked to a class, the entire concept of library symbols is analogous to OOP classes. Flash even auto-fills your symbol linkage with the symbol name when you select it to be exported for ActionScript. It is easier to find things in libraries where things are named exactly by what they are associated with. It’s common to see developers name their symbols with an ‘mc’ prefix. The prefix is part of hungarian notation, which should be used for instances and members only. Sometimes prefixes are used so Flash will sort symbols according by their type. If this is preferred, folders should be used, or a standard should be developed among the team.
Define variable scope as privately as possible.
Private scope is more than just a way to ensure parts of a program don’t interfere with each other. It also helps programmers understand the intentions of the original programmer, and implications of future alterations to code. It is not uncommon to find many variables left public unnecessarily, just by habit or convenience. This is a source of confusion for developers who consider all public members as intended for public use. Sorting this out costs time. This can be avoided by defining all members as private by default, unless specifically intended to be used publicly.
Don’t leave code that needs to be changed before each delivery. Make a dynamic switch.
Often, programs need slight modifications to run in testing environments, versus where they will be finally hosted. This can be for tracking, localization, assets, media, etc.. It’s common for developers to just make a note, and remember to make this change every time a new deployment is delivered. This is an extra step that costs a small amount of time on each delivery, but also opens the door to a mistake, by possibly delivering a project that is incorrectly configured. A better solution is to write switches in the code that automatically handle this. We can write a few lines that read the URL, and detect if a project is being hosted from specific domains, and switch out behavior based on keywords matched in the URL.
Don’t use upper case in file names for files that get deployed.
Some servers are case sensitive and some are case insensitive. If you happen to be working from a server that is case insensitive, an incorrectly cased filename can go unnoticed. It may only become a problem when the program is live. This can break the entire program and be hard to solve. As a general practice, if a file is to be served up, use all lowercase filenames with underscores to separate words, such as “your_file_name.js”.
Use concise, specific variable names
Imagine a public member named some commonly used combination of characters like “map”. Now imagine a global search to find every reference to that member. Your search may return hundreds of lines that are irrelevant. Besides that, “map” isn’t completely descriptive of what the member actually is. Once you have named a member with consideration to being descriptive, and uniqueness with regard to global searching, you have killed two birds with one stone. “gameTileMap” is much harder to mistake by coders, and by search algorithms. The larger the scope of the member, the more carefully it should be considered. Conversely, super long member names are totally unnecessary. If your method name comprises a nearly complete sentence, you should consider using code comments for this information instead. No one wants to remember or type your 100 letter method name.
Spell things correctly.
It’s easy to be passive about fixing spelling mistakes. But trying to remember and retype someone else’s misspellings is silly, but not so funny when misspellings have worked their way into different facets of a project where a global replace alone wont fix the issue, like assets, linkage, or timeline code. It’s worth the trouble to stop yourself early and correct a mistake before it propagates everywhere else.
Do not use internal (company) code libraries and frameworks as stub code.
Internal code libraries are infinitely beneficial, but having different versions of them in every single project isn’t ideal for several reasons. It limits problem solving abilities, and makes it extremely difficult to update to newer versions of a framework. When problems arise, it is difficult isolate if there is a problem with the a framework, or if it’s because of modifications. It commits on-going projects to dated frameworks and discourages advancement of extensibility for code libraries.
Avoid long lines of code that necessitate horizontal scrolling.
Equations can get pretty long. Break them down into variables so they can be easily understood, and so horizontal scrolling isn’t necessary to see everything onscreen at once, and word-wrap doesn’t cause things to get really hard to look at.
Don’t recompress JPGs.
JPGs use lossy compression. Recompressing JPGs is analogous taking a copy of a copy on a zerox machine. It loses quality every time. Even worse than that is that the compression algorithm sees the edges of compression artifacts as necessary detail and tries to preserve them, resulting in larger file sizes, and lower quality. Even if you think it looks ok, I can usually tell when this has been done, as it has a distinct look to it. It looks bad. Keep your work looking professional, and avoid this practice as much as possible.
Use AS3 vectors where possible.
Strong typing is saves you time. AS3 vectors are more strict, but it is worth becoming proficient with them.
Store similar elements in arrays, vectors, maps, or dictionaries where possible. Use loops to access their properties.
It’s pretty common to see many lines of code that are nearly identical, with only a character or two difference between each line. This usually because similar elements were not stored in a way that can be accessed with a loop. This makes alterations to your code tedious, and opens it up to bugs every time it is edited. Start of on the right foot, and store similar elements in systematic arrangements objects, such as arrays. This also has a payoff for element spacing and animation which can be done mathematically inside the loops.
Have debug resources on hand, and know how to use them.
Vizzy, Flash Debug Player, Chrome Canary, Firebug, IE Watch, HTTP Watch, Charles Web Debugger, Virtual Box, etc… In the 11th hour, your project has finally gone live, but it’s broken, and you don’t have access to the server where the deployment is hosted. We need to be as responsive as possible in these situations, and to do so, each of us should be set up and familiar with all the resources necessary to isolate any bug that may arise.
Use bandwidth limiters.
Many coders only think of bandwidth limiters as a way to test page load time. They can actually help you find problems with your site that weren’t apparent otherwise. It’s easy to forget that our bandwidth is wicked fast. I’ve seen preload scripts behave bizarrely once tested in real life bandwidth scenarios. I’ve also seen sites break entirely, because asynchronous processes were firing out of order once bandwidth was a factor. Bandwidth restriction is an essential part of testing.
If you haven’t heard of design patters before, you should take some time and learn what they are. Wikipedia: “In software engineering, a design pattern is a general reusable solution to a commonly occurring problem within a given context in software design.” There are many design patterns, and some of them you use on a daily basis, though you may not have realized at the time. Events are a part of the observer design pattern. Singletons are another. Design patterns are an enormous topic, and many a heavy book have been written about them. For larger scale types of programs developed by teams of engineers, they are a necessity. For projects with a smaller scope, and less requirement for ongoing maintenance, you will see fewer of them, but they are still important. An understanding of them reaps benefits to you as a coder. Even if you don’t use them, you may use concepts from them hear and there, but more importantly, it will change the way you think about your code, and help you develop in more sophisticated ways.