Thursday, September 03, 2009

Coding standards and religion wars

A common tip in the "guidelines for good code" posts is to adopt a coding standard and stick to it. What is a coding standard and why you should adopt one now? Don't be worried about which one.

A coding standard gives a coherent look&feel to your code, promoting predictability. For a software system, predictability is almost always a good feature since a developer cannot hold a picture of all the code in his head, and has to guess what other unit of the systems will do in some situations as they collaborate with the one under development.
This applies on a behavior level, but also on a more physical Api discovering; while the description of the correct behavior resides in specification, tests and mocks, the appearance of the code and the classes and methods it expose is generated by a coding standard. If the names of methods (and their capitalization) are analogue and have the same structure, it becomes easy for a developer to program against it.

Code reading and analysis
Every coding standard forces an organization in the code to make it readable. Indentation, tabs vs spaces, control structures organization are all techniques which maintains order in a codebase, but there is a free choice
As an example, let's talk about the Java methods bracing in contrast with the php one. Java prescribes the developer has to put the opening brace { on the same row of the method signature definition; php coding conventions instead tell the developer to place it on the subsequent row, at the same level of indentation of the signature:
void doSomethingJava() {
// ...
public function doSomethingPhp()
// ...
There is no functional difference in the two cases; compilers and interpreters ignore whitespace, indentation and line breaking. All these rules serve no functional purpose.
The problem they address is style: a book can be beautiful and well-written, but if it's printed in an unreadable font, in pages of different sizes kept together by nylon threads, it will be very difficult to read without exhausting your nerves. The importance of a coding standard does not derive from which one you choose but from the constance in sticking to it, particularly in large or open source projects where many different people patches and rewrites code at the same time.

Subjective rules
Meaningful variable names is a subjective rule, since it cannot be cheked to a great extent from a static analysis tool. However, it is applied to improve the readability of the code, again. The convention on capitalization (CamelCase for instance) is a real coding standard, but the identifier names is more a matter of programming style, as long as you do not call variables $a1 and $a2.

If you are not organizing your source files, adopt a coding standard now. In the php world, Pear coding standard is the most famous one: I use Zend Framework one which is nearly identical to it. However, every project has conventions: if you want to be considered serious, follow a standard.

1 comment:

Wes said...

Good Explanation! I see a lot of people completely ignoring standards and even worse, I see organizations letting them get away with it.

This is some good stuff.