By: David Mytton

September 23rd, 2004

Reader Rating: 7.5

The best applications are coded properly. This sounds like an obvious statement, but by 'properly', I mean that the code not only does its job well, but is also easy to add to, maintain and debug.

This "maintainable code" is a popular talking point among those involved with PHP and probably with other languages as well. There's nothing worse than inheriting an application or needing to make changes to code that requires a lot of energy to decipher – you end up trawling through lines and lines of code that doesn't make its purpose or intentions clear. Looking through unfamiliar code is much easier if it is laid out well and everything is neatly commented with details that explain any complicated constructs and the reasoning behind them.

In this article, I'll explain why coding standards are important not only to the individual developer or development team, but to the script users as well.

The Problem

When we learn a new language, we usually begin to code in a specific style. In most cases, we'll write in a style that we want, not one that has been suggested to us. But once we start to code using a particular style, like a spoken language dialect, it will become second nature -- we'll use that style in everything we create. Such a style might include the conventions we use to name variables and functions ($userName, $username or $user_name for example), and how we comment our work. Any style should ensure that we can read our code easily.

However, what happens when we start to code bigger projects and introduce additional people to help create a large application? Conflicts in the way you write your code will most definitely appear.

The Solution: a Coding Standards Document

A coding standards document tells developers how they must write their code. Instead of each developer coding in their own preferred style, they will write all code to the standards outlined in the document. This makes sure that a large project is coded in a consistent style -- parts are not written differently by different programmers. Not only does this solution make the code easier to understand, it also ensures that any developer who looks at the code will know what to expect throughout the entire application.

Coding standards are great -- but how do you decide which standards you want to apply, and how they will be defined? When you formulate your ideal coding style, you should think about these points:

1. Can you actually read the code? Is it spaced out clearly?


• Do you separate blocks of code into 'paragraphs' so that different sections are easily defined?
• Are you using indentation to show where control structures (if, else, while and other loops) begin and end, and where the code within them is?
• Are your variable naming conventions consistent throughout the code and do they briefly describe that data that they'll contain?
• Are functions named in accordance with what they do?


2. If you come back to the code in a few weeks or months, will you be able to work out what's happening without needing to look at every line?


3. How are you commenting the work?


4. Have you used complex language functions/constructs that are quicker to write but affect readability?

Once you've considered those points, you can begin to draft your coding standards. Consult with your team members (if any) and compare how they code to your own style -- you shouldn't force total change upon everyone. Compromise and incorporate elements of everyone's style. If someone has been coding in a specific way for a long time, it will take a while for that developer to change to the new method. Developers will likely adopt the style gradually, just as an accent develops over time.

Create Maintainable Code

As we said at the beginning of this discussion, you want to create maintainable code. If you stop developing a project, return to it several months later, or hand development over to someone else, you (and other developers) want to be able to understand what's going on in the code. We keep mentioning 'readability', but what actually constitutes "readable code"? The answer to this question will obviously differ for each programmer, but I believe there are some common fundamentals, which we'll discuss now. I've used PHP to outline various styles here, but similar ideas will apply to other languages:

// Method 1  
if (condition)  
function1($a, $b, $c);
for ($i < 7 && $j > 8 || $k == 4)  
a($i);

// Method 2  
if (condition)
{
   get_user($id, $username, $key);
}

for (($i < 7) && (($j < 8) || ($k == 4)))
{
   display_graph($value);
}

Here are two ways we might write the same code -- you can see the difference between easily readable code and complex, but more quickly written code. Even if you don't know much PHP, you probably noted that the second snippet is much tidier and easier to understand. I've named functions using a verb (get, display), used variable names that describe the data they contain, and used brackets to help show what the for condition is. Not only that, but I've also included the braces for the control structures and used indentation to show which code appears under each structure.

Your own idea of readable code might differ slightly from this, but I'd bet that every PHP coder could easily understand what's going on in the second example. The first example, however, takes extra time to comprehend. Sacrificing extra lines and whitespace will make a noticeable difference to the layout of the code. As you develop coding standards, try to ensure that they allow anyone to work out the code in future!

Different Standards

PHP example code and Pear modules (etc.) generally use the Pear Coding Standards [1], which are slightly different from the method I used above.

I have my own personal coding standards, which I adopted from the phpBB Coding Standards [2] because I liked the way they were written. For example, in my own standards, I put the braces for control structures on a new line:

if (condition)
{
   get_user($id, $username, $key);
}

But in the Pear standards, the first brace is on the same line as the if (condition):

if (condition) {
   get_user($id, $username, $key);
}

The standards you choose are all down to personal preference and what you find easiest to code and read. To get you started, I've included a copy of my own standards for you to download [3]. Happy coding!

[1] http://pear.sourceforge.net/en/standards.php
[2] http://area51.phpbb.com/docs/guide-standards.html
[3] http://www.sitepoint.com/examples/standards/codestandards.zip