Choosing a Coding Standard

[webnetics]

How many times have you reformatted a co-worker’s (or former employee’s) code to make it more readable? How many times has someone done the same to your code? We can consider such actions to be a net loss of coding time.

So we decide to use a coding standard within Virtual Web Designs.

Taken from our own internal document VWD-129 Issue c

Coding standards are very important:

file naming and placement
variable, function, and class naming conventions
indentation rules
documentation and comment guidelines
… and much, much more.

Rather than creating our own standard, we decided to adopt a public standard.

The benefits of using a public standard are:

It’s programmer-neutral.

Instead of one programmer or group of programmers dictating their own preferences, choosing a public standard is a programmer-neutral solution.

The issues have been settled.

A public standard will have undergone heavy debate already. While not everyone will be able to agree that the outcome is the best one, everyone has agreed that the standards represent the best collective solutions.

Use it as hiring criterion.

When adopting a public standard, you can use it as a criterion of employment: “Applicant must know and be able to use XYZ Coding Standards.”

It’s better for code distribution.

For instance, if you’re following PEAR Coding Standards, your code will be in a format—both the physical, on-disk format, as well as the format in which the code is written—that can easily be packaged and installed using the PEAR installer, or via a PEAR channel.

So, what public standards are available? We decide to look at some of the most popular standards available:

PEAR, at http://pear.php.net/manual/en/standards.php
Zend Framework, at http://framework.zend.com/manual/en/codi...ndard.html
eZ Components, at http://svn.ez.no/svn/ezcomponents/docs/guidelines/

With some additions of their own, these coding standards were all originally derived from the Horde project.. Horde and PEAR coding standards are identical at this point. Zend Framework standards basically follow those of PEAR, with a few slight changes; all in all, however, Zend Framework remains compatible with PEAR. eZ Components standards are basically only used by the eZ Components project and those developers who code with it.

PEAR coding standards are widely adopted, and are used in high-profile projects. Overall, when it came to a choosing a standard we decided on the PEAR’s standard, as we found this to be the best option and used with most software houses.

The basics of PEAR coding standards are summarised as follows:

• There is one class per file.
• Underscores in class names map to the directory separator: for example, Net_SMTP maps to Net/SMTP.php.
• There is One True Brace: class and function declarations have the opening brace on the following line at the same indentation level as the declaration; in other control structures, the opening brace remains on the same line as the statement.
• Code indentation should equal four spaces per indentation level.
• Variables, functions, and classes are named using camelCase or studlyCaps; variable and function names should begin lowercased, while classes should begin uppercased.
• Private and protected properties and methods should be named with a leading underscore.
• All classes, functions, and methods should have a docblock.

Summary

Using a coding standard lets us ensure that you’ll we are able to maintain the code of are fellow programmers, and vice versa.