Our Blog

where we write about the things we love



Documenting coding standards - less is more

A colleague and I were recently invited to provide feedback on a client's coding standards and were sent a 60+ page document to review. In preparation for the meeting I diligently started to go through each section providing comments and suggestions as I went. But after about page 30 my concentration began to wane and my comments grew more and more sparse. The moral of this story...

If someone that's being paid to review your coding standards is struggling to get through them then you can bet your bottom dollar your development team won't be reading them either.

Don't get me wrong - documenting the standards to which you will hold your developers is important. But you've got to make some decisions about what should and should not be included.

So I find myself documenting standards for documenting standards - oh the irony.

Don't Document The Obvious
A good example of this was in the document we reviewed. Ensure that code is written that can handle NULL values in database columns correctly without generating runtime exceptions. Ah, OK then, thanks.

Do Document Standards That Are Commonly Different Between Companies
Lots of standards are simply personal choice. For example, whether member variables should be prefixed with _ or m_. In these cases you don't even have to justify why - it's just the way it is.

These sorts of standards are really useful to have written down and handed to new employees.

Don't Document Things That Will Date
Unless you want to spend time updating your standards every few months avoid specifying anything that is likely to become out of date. For example:

  • Specific versions - if you wrote about the company's standard to use Visual Studio 2005 what happens now that half the company have upgraded to 2008?
  • A less obvious example was in the document we reviewed - "Do not use dynamic SQL scripting under any circumstances." A few years ago this was a common recommendation since older versions of SQL Server weren't very good at optimising dynamic SQL. This is no longer a problem and the popularity of ORMs makes it a common occurrence.
  • There is a similar risk in documenting patterns and best practices - over time patterns come and go and evolve. There are much better ways of socialising these things within your company that don't require you to write them down (see below).

Do Document Things That Should Be Checked During Code Reviews
It's hard enough as it is to get people to review each other's code without requiring the reviewer to reference a hefty tome of standards. If you have documented only the most important things it's a lot easier to enforce and socialise.

Do Provide Examples
Coders are typically better at reading code snippets than words - enough said.

Don't Document Recommendations
OK, I'm going to go out on a limb here but some of the most useless standards/best practices I've read are recommendations that are meaningless unless you spend a lot more effort explaining the why's and when's. I’ve seen the following in a number of standards documents:

  • Do favour using classes over interfaces
  • Do use base classes
  • Do think twice before making a member virtual
  • Do use regular expressions whenever possible rather than writing JavaScript

Each of these may be true in certain examples but you need to have way more context. Writing them in a document doesn't help someone understand them - and it certainly won't make them follow them.

Do Consider Alternatives To Documentation
I think there's something in a developer's genetic make-up that gets an immense amount of satisfaction in writing documents like coding standards. And in many situations the primary value of the document is in the pleasure it gave someone to construct. It's almost like writing the code itself but without having to actually solve a problem. Everything is neatly laid out, each standard has a reference number, it's all very black and white. Coding in the real world isn't always this satisfying.

I am really interested in other mechanisms that can be equally effective in encouraging consistent, quality code.

  • Leading By Example - assuming those that are leading projects are on the same page (and this can be achieved through face-to-face meetings - yes you'll have to talk to each other) the best way to teach people what you expect of them is to do it yourself. It won't take long before members of your project team are all coding to the same tune - you'll be amazed at how quickly people can simply look at a piece of code and instinctively know what's not right.
  • Code Reviews - a common mistake is to assume that code reviews are done by senior developers to ensure the juniors are towing the line. There is just as much value in a junior reviewing the code of someone more senior - for one they get to see for themselves how it should be done (hopefully!) and equally importantly it keeps the seniors on their toes. Code reviews are a good way to enforce common standards (that may well be documented) but also project related or transient standards (that probably aren't - and shouldn't be). For example, your team may have decided to follow a certain pattern or use a particular technology.
  • Self Fulfilling Prophecies - sometimes all you need to do is talk about something enough and it becomes true. A while back the senior members of our development team decided that we should follow an MVC style (or variation of) on all our applications. This wasn't written down anywhere but we kept on mentioning it at team-wide meetings (including white lies like, "...now that we are all using this pattern..."). Eventually our Team Leads all started using it and before long we are at a point where all our projects are actually really using it. This approach can be a really useful tool in general - it's really important to sing your own praises, hype up your successes - you'll be amazed how this affects the way people actually behave.

So before you create your own War and Peace think about whether this is the best way to get your message across.

Posted by: Andrew Tokeley | 12 August 2008

Tags: Coding Standards

Top Rated Posts

Blog archive

Stay up to date with all insights from the Intergen blog