Coding standards exist to make teams more productive. In theory, they make code easier to understand, alter, and test. In practice, they can create a dangerous amount of meta-work; teams re-write existing code over and over in pursuit of the most correct and elegant solution. Unfortunately, the meta-work problem seems worse on teams where everyone is engaged, passionate, and obsessed with doing the right thing.
As a consultant moving from project to project, I've found that excellent discipline with a rigid coding standard contributes far less to a project's success than excellent developers who are interested in results. Inconsistent coding styles are a minor nuisance to amazing developers. They're productive with or without consistency. Granted, if they encounter inconsistent code they'll ask about the current standard and stick with it. They won't, however, insist on updating every line of code in the project to the current standard. They don't insist because they've seen best practices come and go. The correct way of doing something today is not the same as the correct way of doing something tomorrow. If it was, your coding standards wouldn't evolve. So, if the correct way of doing something changes with time, maybe our definition of "correct" is broken.
That's not to say that standards don't matter. Just keep in mind that the goal of standards is productivity. If you can't guarantee re-writing to a new standard will pay for itself in the long-term, then don't waste time on it. It's far easier to justify a new standard in new or refactored code. Elegance is cool but it's not the same as results.
I work with a team that grew from 2 developers to 10 in less than a year. I was number 3, and the first to raise a coding standards issue. The two original developers had been working side by side for a few years and they'd adopted a common standard that seemed alien to me. We had exactly the same problems you are describing.
What we did was:
Research coding standards
We spent a few days checking out established open source projects. We knew the team would expand rapidly and we were looking for real solutions based on real projects not some generic guidelines. Also we didn't care for the optimal coding standards, but for a set of rules and guidelines that would make sense and not call for the refactoring of all of our codebase. We were looking for a coding standards hack if you will.
The three of us decided that the best coding standards out there for an established PHP project were those followed by Zend Framework. Fortunately the Zend Framework people provide a very comprehensive coding standards document.
Creating our own coding standards
Of course applying another project's coding standards on our project as is didn't make sense. We use the Zend Framework document as a template:
- First we removed everything that didn't apply to our project
- Then we changed everything that we perceived as a matter of style to our style
- And finally we wrote everything down
So we had a fairly large document at our hands, stored in our fancy wiki, it was a nice read, agreed upon by all of us. And completely useless on its own.
Staying true to our promise
Our codebase at the time was about 1*10^6 sloc. We knew that since we adopted formal coding standards we had to start refactoring our code, but at the time we were pressed with other issues. So we decided to just refactor our very core libraries, a mere 5*10^3 sloc.
We assigned one of us to be the coding standards master (we used local profanity in place of master) with the responsibility of checking and enforcing the standards. We recycle the role every few sprints. I was the first, and it was a lot of work, as I had to monitor almost every commit.
We had several new discussions and small addendums to the original document during my tenure, and finally we had a somewhat stable document. We change it every now and then but most of these changes are on new features of the language, as PHP 5.3 was a major release in all but name.
Dealing with the new guy
When the next new guy arrived, it was time to put our coding standards to the test. After a small introduction to our codebase, we asked him to evaluate our coding standards document. He almost cried. It appeared that he did everything differently.
As I was the coding standards master at the time, it was up to me to evaluate his input and revise the document accordingly. His proposals were:
- Matters of personal style (summarily dismissed)
- Standards that made sense to his Java background but no so much with PHP (dismissed)
- Conventions that he carried from his brief exposure with PHP (some were dismissed, but a lot proved to be popular conventions that we never thought of or found out in our initial research)
For the next couple of weeks he was assigned a simple task: Bring several parts of our codebase up to date with the standards. I had to carefully choose those parts based on a few rules:
- Code should be relatively easy for someone unfamiliar with our codebase (and PHP in general)
- Code should be on what he was hired to do
I monitored his process and he did a fine job. We identified several parts of code that was impossible to fit our document and revised accordingly (code and / or standards, whichever made more sense)
And then another new guy arrived. We repeated the process (different master this time), and it worked again. And again.
In conclusion
- Create a coding standards document, but make sure that your standards are not exclusively your own but do reflect common standards in the wider community of your platform.
- Assign a similar role to our coding standards master. Someone to monitor at least new code, and especially new code from new members. Recycle the role, as it's extremely boring.
- Always evaluate input from a new member. Always revise your standards if it makes sense. Your coding standards document should be evolving, but slowly. You don't want to re-refactor your codebase at each iteration.
- Allow for some time for each new member to learn and adapt to your standards and conventions. Learn by doing works best in these situations.
- Wiki works wonders for such documents.
- Code reviews work wonders for any situation!
At some point in the process it was suggested that we use a pre-commit hook to automate checking of the standards. We decided against it for a variety of reasons, there are some interesting discussions on StackOverflow on the issue:
Some are PHP specific, but the answers apply to all platforms.
Best Answer
Follow an arbitrary rule they said.
It'll be fine they said.
We have discovered the source of all perfection they said.
There can never be anything that breaks the rules they said.
They obviously never wrote code...
Having a formatting guide is great, it helps people answer the same question with a predictable answer.
But - and there is always a but - you are writing code, because it has never been needed to be written in this way, for this purpose, before.
Therefore it is new, it is novel (even if it is an unoriginal copy, paste, and rename), and they have never seen it before.
How could they have written a 'rule' that is universally applicable without having considered the entire universe? Hint - They could not have...
At its best this 80 character limit might be a generally useful rule of thumb. And I can see that it does have some basis in print media, and well formatted documents.
However you have forgotten something - utility. Which I presume to be the original intent of the rule of thumb 80 character limit.
Now which one is more professional for a news-columnist, a book author, or a web designer? Probably line-wrapping the link at about 80 characters, using the conventions and standards of their medium, to clue the reader into, or using the technologies available to present the link in a utilisable manner.
Which one is more professional for a programmer?
If you had a choice of hiring between two programmers:
But equal in every other way. Which one would you hire?
I would hire the one who did not, for they were professional enough to understand the goal, by not making life harder for the next developer.