back

Coding standards: What are they and why should you use them?

by James Polanco

Over the last few years, front-end web development has grown from a semi-straightforward approach (that is, individual HTML pages sprinkled with Flash and JavaScript) to a much more complex application-based design (that is, Ajax, Flex, and Adobe AIR applications). The level of complexity is similar to what desktop software developers have been dealing with for years. Yet with this complexity, many front-end developers still look at web development as it was in the old days and often do not take the time (or don't know how) to implement coding standards within their applications.

In this article, I explain what coding standards are and why you should use them, while providing some real-world examples. I hope to initiate a conversation in the community to try to create a more unified approach to how we code in general. This article is somewhat Flex-centric because that's the technology I work with, but these standards can be adopted for any type of application development.

What are coding standards?

Coding standards are a set of guidelines that help developers write code consistently over time. By writing consistent code, developers help both themselves and, more importantly, other developers who work in the same codebase. These coding guidelines cover two basic areas of the coding process.

The first is how you visually write your code, which is often called code conventions. Code conventions define how you name your variables, methods, classes, packages, and comments; how you organize file structures; and so forth. Conventions define how your code is visually presented to the developer.

The second aspect of coding standards is the adoption and implementation of code design patterns. A design pattern, such as Model-View-Controller (MVC), is an abstracted guide to solving a common problem developers face. Taking this abstraction and defining guidelines around how it should be implemented in code creates a consistent experience and structure for your code. In most cases, when a coding standard is defined by a company, by a team, or for a project, the focus is on code conventions. Yet defining how code design patterns are implemented is just as important to the overall standardization process as how the code is written.

Why use code standards

So now that we have defined the realm of coding standards, why should we use them in our projects? The most obvious example of standardized coding is when you have a development team greater than one person — for example, an Adobe Media Player type project or an open-source project.

Imagine trying to maintain a code base that has n developers all writing code with different naming processes and file structures. As a new developer joining the project, how do you find things? When you want to make a change or add a new class, what is the best way to do that? If you need to fix a bug in someone else's code, how do you approach it? In a free-for-all codebase, you would see what is often referred to as spaghetti code. The code is hard to follow because it changes structure line by line, method to method, and class to class. The code is unpredictable and quickly becomes a nightmare to follow, manage, and debug.

Coding standards are not just for large projects; they also help individual developers on small projects. If you have been developing for any length of time, you have had to return to code you wrote months or even years ago at some point during a project. If you didn't take the time to comment your code or follow a predefined code structure, it can be tedious and frustrating to try to figure out what your code is doing and how it is executed.

Unfortunately in the Flash development community, a bit of an underlying lone wolf developer mentality exists. This is especially true for Flash contracting and agency projects. This is a world of insane deadlines, and the mantra is "Just get it done." Too many times, I have heard fellow developers in this situation say that they don't have time to follow standards or, even worse, that they don't comment because it guarantees they will be hired back to fix the code if it breaks." Amazingly, I have heard that last comment more than once.

The idea of protecting work by obfuscation is just as bad as security through obfuscation. It may work in the short term but, in the long run, developers just hurt themselves. They may get a new contract where they have to work on a large codebase, and because they have never practiced coding standards, their code could become a detriment to the team, no matter how experienced they are. Another possibility is that the client knows a bit about coding and, after seeing the sloppy code, does not hire the same developer when it's time for the next revision or project.

As we enter the world of rich Internet applications (RIAs), we are no longer talking about banner ads and interactive marketing experiences that have a lifespan of one to six months. RIAs are software on the web, and the idea of throwaway code needs to be re-evaluated because new versions and updates are released on a regular basis. In this world, it's no longer economical to rewrite the whole code base each time a new version is released. Coding standards can help maintain a clean and scalable codebase that can last for years.

Examples of coding standards

Coding standards do not have to be rigid documents that force all developers to code space for space the same way. A good starting point is to look at recommendations that have been put out to the community.

A great example is Adobe Open Source's Flex SDK Coding Conventions and Best Practices. This article is important for open-source projects because anyone can extend the codebase and submit back to it. The core focus of the article is code clarity. Avoid abbreviations, comment well, and keep a constant package structure. By following these conventions, developers can submit code that fits seamlessly with the existing base, enabling them to understand what the code does.

Coding standards should not be hard for developers to follow. They take some practice, but they soon become natural. A simple example is taking a few extra minutes to comment your code. It doesn't have to be a whole document, but use a few words to note what you are doing. One developer I worked with showed me a great tip years ago to prototype with comments:

Public function parseData(data:Object):void
{
  // validate the data
  // convert into data objects
  // dispatch to listeners
}

By prototyping with comments, you already have the stubs for both flow and commenting. As you write the code, update the comments or add more if necessary. By adding simple comments, you make your code easier to read for other developers and yourself when you have to come back to it. These are just a few basic examples of how code conventions can be applied.

Now, how do code design patterns play into code standards? I recently wrote an in-depth post on the Flex code-behind pattern. This pattern was adopted from the ASP .NET model by early Flex developers. The idea is that you use MXML for layout, and all scripting logic goes into a backing class that the MXML extends from. For Flex 1 and 1.5, developers leveraged a bug in the compiler that automatically mixed the class into the MXML. Now that ActionScript 3.0 does not support mix-ins, we use the same basic code-behind process, yet it is now an inheritance extension.

In the projects I worked on, we adopted this process, and it has now become a coding standard for the existing codebase and all future projects. This kind of pattern is more about code structure and readability so it is easily adopted into a coding standard.

Micro-architecture and framework implementations (such as Cairngorm, Dojo, or Spry) define a coding standard as well. By implementing micro-architecture into your application, you automatically follow a pattern and are given a consistent structure for all your code by default.

An added benefit of micro-architecture adoption is that as you work with new developers that have experience with the architecture, they can get up to speed and contribute much faster because they are familiar with the overall code structure and development process.

It's a start

This article barely scratches the surface of coding standards, but I hope it brings more exposure to the benefits of using them. As more coding standards are developed and proposed to the community, we need to think about process development and workflows.

Once we start talking about processes and workflows, we realize that coding standards are not just developer-centric but they are also important from a team, department, and even company-wide perspective. Coding standards are just one element of the workflow process, and by adopting them, you can more easily grow your team and project.

The above coding standards examples are simply proposals to start thinking about possible future standards. These standards are always guidelines and should not be rigid rules for how a developer writes code. If you prefer to cuddle your curly brackets, go ahead. But, at least consider how coding standards can help decrease overall development time and organize your existing and future projects.


James Polanco is the co-founder of DevelopmentArc, a boutique consulting firm that specializes in web application and user interaction front-end development. James specializes in application development and has provided system architecture and code development on projects such as Scion.com, Toyota.com, and Adobe® kuler Desktop. James was also a Senior QE Team Lead on the Adobe® Flex® Builder™ team focusing on ActionScript® 3.0 development harnesses and automated testing systems.