5 Reasons Coding Standards Are Essential
Whenever you’re developing web applications, are you consistent, do you apply a coding standard? Do you and your team have an agreed upon coding standard? If you don’t, you’re asking for trouble. Here’s Why
Whenever you’re working on a project, are you consistent? Are you consistent in your coding style, consistent in your documenting, consistent in your database naming conventions? Better yet, do you and your team have a coding standard which you consistently adhere to?
If you don’t, you’re buying yourself and others a world of pain - which is painlessly simple to avoid.
Today I’m banging the drum, shouting from the street corner, calling from the cathedral spire, imploring you to do one thing, above all else - pick a coding standard and then BE CONSISTENT!
I don’t care if you hate standards, I don’t care if you think all of them are flawed, I don’t care if you feel locked in, chained up, with all your creativity is stifled.
Because if you think this way - You’re Wrong.
Poor, Inconsistent Code - Causes You Pain
I used to think this way but saw the, proverbial, light. Why am I banging on so hard today? At Malt Blue, I have the joy of working on a wide range of freelance web application projects, both big and small.
However a recent project I took over gave me reason to pause. This project, had a lot going for it. It seemed to have had good intent with the basics of a meaningful design behind it. It had potential to be something really worthwhile. It could have been a maintainable project which wouldn’t have ended up costing the client quite a lot of money to support.
Unfortunately, a number of things were done wrong, the key being inconsistency. This led to a series of problems in the code, which I’ll summarize for the sakes of brevity. The are as follows:
- Extremely time consuming to get to grips with the code base
- Code was not intuitive or semantically meaningful
- It was hard to see what linked to what - and more importantly - why
- Time was required to be spent re-reading the same blocks repeatedly for understanding
- Very difficult to tell where to find relevant sections of code
Here’s some examples of what was encountered:
- The code base was littered with large swathes of commented out code
- SQL queries were written using a DB abstraction layer, then later composed manually
- Variables and configuration options were named “my”, “m”, “last” and so on
- Multiple functions, with different names, in different modules performed nearly identical functionality
- Operations were performed in segments of code, multiple layers deep, with no semantic direction
To cut a long story short, countless hours were spent, searching, tidying, documenting, trying almost in vain, to understand a code base needlessly.
If the earlier developers would have adhered to a coding standard, not to be confused with a coding style, a lot of this could have been avoided.
Now I know some people hate coding standards. But if they want to waste time, both theirs and others, I never want to work on their projects.
So find a standard which works for your business, your organization - you - and stick to it ardently. I don’t care which one you adhere to (within reason) - so long as you adhere to one.
There are a wide range of standards to choose from. Personally I use the Zend Framework coding standard as I primarily work on Zend Framework-based projects.
Now that I’ve had a rant, here’s the benefits they provide:
Your Code is Easier to Read
When you use a standard, your code is readable, both to you and others. Why, because it’s consistent. Now, it might not be the best standard, but at least, in a short period of time, you will be able to follow the flow.
Take the following code for example. To some it may seem trivial. But if you imagine this throughout a code base (even with a formatter in an IDE or script) this code is hard to read. Let’s leave out the obvious spelling mistakes
Your Code is Easier to Understand
This is perhaps the biggest point for me. Whether it’s the variable naming convention or otherwise, the intent of your code is easier to follow. Take the following example:
I’m not a rocket scientist or a Rhodes scholar, but neither am I unintelligent. But I can’t infer what *nice1 and *nice2 are meant to be for.
Can you? What do you think the class it was in may have been doing? Here’s a tip, it was for validating contact information.
Your Code is Easier to Maintain
From a model class in the same code base, here’s another example:
The class constructor initializes a protected member variable, _db, with the application database connection, which these functions use. However, they’re doing nothing more than wrapping internal functionality. Here is another example:
This doesn’t strictly fall in to the above category - more in to the DRY. However, what is the purpose of writing code which replicates existing functionality, i.e., PHP DateTime, Zend Date et al? Why would you do this?
Why would you write functionality yourself which already exists, has a range of high quality unit tests, has had 10’s, 100’s or 1000’s of eyes on on it, verifying its quality, holding it up to scrutiny?
Please don’t do this - unless there’s a really good reason for it.
Your Code is Easier to Collaborate On
As a result of all of these points, code is harder to collaborate on. Why? If it’s hard for one person to work on a code base without wondering where errors might turn up, extrapolate it over a team of 2, 3, 5 or more.
With clean code and a clear and concise standard which’s adhered to, at the very least ensures if you’re going to write rubbish code, it’s clear rubbish.
When you don’t though, as I’m sure you don’t you’re well on your way to building high quality, maintainable code, now and in to the future.
What are Your Horror Stories?
You’ve heard mine, now I want to hear your worst experiences. What have you encountered? More importantly, what have you done about it? Was it too hard to overcome or was it manageable?
Share with us all in the comments today. The best (or is that worst) story gets a free copy of the next edition of PHP Architect magazine.
image copyright marsmet481
You might also be interested in...
- How Simplicity Leads to Greater — Productivity, Quality & Satisfaction
- What Is a Professional PHP Freelancer?
- Zend Framework 2 Modules - The Application's Heart
comments powered by Disqus