Coding standards are one of those documents that managers often feel obliged to produce, so they are frequently written without any clear sense of purpose. A number of different motives can inspire coding standards - not all of them very positive.

Why are you writing coding standards?

Coding standards should be created to improve the quality of code and the productivity of your team. More often that not, coding standards are just a "box-ticking" exercise and are produced for the sake of it, or just in case anybody asks awkward questions about development management. This is a missed opportunity as coding standards can be a means of improving code quality and code cohesion - so long as they are produced in an appropriate way and for the right sort of motives.

Ideally, coding standards become a place to gather collective wisdom and document commonly accepted best practise. They are a means of adopting a set of common conventions and approaches that allow developers to communicate freely with each other through code. They can also act as a guide for newcomers to let them know the standards and conventions that are expected.

On the other hand, they can also be used as an instrument of control. Weaker development managers who just don't trust their teams can use them to harry colleagues into working "their way". This tends to produce standards that are over-detailed, nit-picking, inappropriate and plain unreasonable.

Coding standards should be reasonable

It's important that any standards should be reasonable and should not just be an expression of your own preferred coding style. The risk is that standards can come to reflect your own personal prejudices rather than expressing best practise. Coding standards can become quite restrictive, particularly as authors tend to be seasoned developers who have reached management positions, so are inclined to take a fairly stuffy, safety-first view of best practise.

A good example is the unnamed development shop that banned LINQ statements on the grounds of performance - the rationale being that "traditional" coding approaches will always provide better performance. This is not necessarily the case, of course, but it is true to say that badly-written LINQ statements are often the causes of bottlenecks that are a nightmare to debug. This does bear all the hallmarks of an edict issued by a 40-something development manager who takes a pretty jaundiced view of any innovations that Microsoft add to the C# language. Rather than fighting the tide, in this case it might be more appropriate to provide guidelines for good LINQ statements rather than trying to ban them outright.

Every developer has their own style and the better ones will produce their best work if you give them the freedom to express themselves in code without having to worry about lots of stylistic rules.

Coding standards aren't just about rules

A set of coding standards doesn't have to be a big, bland list of rules and regulations. They are an opportunity to set an agenda, communicate an ethos and spread some ideas. This is particularly important when you have a number of more junior developers on the team, or are taking on a lot of new developers.

For example, the last set of coding standards that I wrote included a section on code smells - describing what they are and how to spot them. They also included some notes around encouraging regular re-factoring, why continuous integration is a "good thing" and so on. All pretty obvious to experienced developers, but it helps to introduce newcomers to some important concepts and established priorities for more seasoned heads.

Don't try to include too much

I have encountered a set of coding standards that spent six pages dwelling on the correct use of spacing in code modules. There were rules to cover pretty much every conceivable type of white space you might ever want to include in a piece of code, along with detailed specifications of how much to apply. Of course, this could have been condensed into a single sentence along the lines of "use blank lines and indentations where appropriate to assist with the readability of code". Or just excluded all together.

This kind of detail bloat can lead to over-long standards that nobody in their right minds will ever want to read, let alone follow. Development standards should not be too proscriptive. Good developers should be given license to design code as they see fit, and less confident developers will only be slowed down by a large set of detailed rules.

Know your audience

There is no "one size fits all" approach to coding standards. Any standards will be a function of the tools you are using, the kind of projects you are working on and the mixture of personalities and talents within your team. The more diverse a team, the more difficult it might be to gain common acceptance for a set of coding standards.

Coding standards aren't an abstract construct - they are a set of guidelines that will be used be real people in real situations. If they hold people back and make their lives more difficult then they are more likely to be discarded. You need to know who you are writing standards for and how they might impact on their work.

Foster collective ownership

Standards are not quite as black-and-white as you may think. Not everybody will agree with every single point of a set of standards and they can become a source of controversy. Ultimately, standards should be a . Consultation helps here, but collective ownership is even better - i.e. passing around responsibility for updating the standards.

It is important that standards are things that the team currently do, rather than being a statement of aspiration. If you have a team that really need to raise their game then standards aren't the right choice of instrument - consider some training first and then introduce some standards.

Don't forget to enforce them

There's no point writing standards if you leave them to gather dust in the drawer. If you want coding standards to help improve quality and productivity then you will need to enforce them.

This will require more than sending them around by email and asking the team very nicely if they'd like to read them. The carrot's all very well, but I'm not adverse to using a little bit of stick to ensure that coding standards are being followed. Tools such as StyleCop and FXCop can be used to remind developers when their code isn't compliant - or tell you when it isn't. You can also introduce standards compliance into your continuous integration process - getting bad code to break builds is a good way of making developers take standards a little more seriously.

Filed under Development Process.