Monday, April 16, 2007

The Purpose of Coding Standards

I'm involved with a group at work crafting the coding standard for test developers across much of Windows.  As part of this exercise, it became necessary to discuss what the purpose of a coding standard is.  Here are my thoughts.

There are two major camps when it comes to coding standards:  those who want the standard to bring uniformity to code and those who want to ban dangerous practices and idioms.  Many who drink from the eXtreme Programming trough fall into the first camp.  I fall into the second.  To see why this distinction matter, consider the eternal question of coding standards:  Which braces style is better?  K&R or Allman?

Those who want uniformity are forced to choose a style.  It usually doesn't matter which one, but there has to be a uniform implementation in the code.  The argument goes like this, "Everyone codes to the same conventions, so that no matter what code you read (and even if you do practice ownership you will be reading code), it looks familiar. We need every bit of help we can get in understanding the system. Making it all look alike is a key aspect of that."  It seems to be asserted more often than proven that uniformity makes sharing code easier.  Because this is asserted without real proof, the extent of its truthfulness is easily made all-encompassing.

There is some truth here.  If the vocabulary of the code is different from one person to the next, uptake will be slow.  By vocabulary, I mean the practices and idioms.  Perhaps the naming conventions of the methods and variables matter.  Certainly the extent and type of inheritance make a difference.  Use of libraries like boost, STL, ATL, MFC, etc. can be problematic if not everyone is familiar with them.

However, is this level of standardization really necessary?  The XP people (at least some of them like Ron Jeffries) seem to say that even small differences like bracing styles make it difficult to work with shared code.  Unfortunately, most of the literature advocating such a stance is short of justification.  Others seem to advocate very terse standards.  At some level differences in style do matter.  At many other levels, they don't.  Where is the line?  We hire smart people.  Let them think.    Prescribing everything that could be done in a programming language is not only very tedious but also gives no room for people to use the tools in the best way given the situation.

Those that don't demand uniformity are allowed to give a different answer.  If there is a big advantage to one style over another, they can advocate it.  If, however, there is not--and in this case there isn't--they can avoid that battle altogether and allow different authors to choose whatever style they are comfortable with. 

In my opinion, a coding standard should serve two primary purposes.  It should preclude those practices that are likely to cause bugs and prescribe those that avoid them.  It should also preclude practices that make maintenance difficult and prescribe those that make it easier.  Thus coding standards are right to talk about comments or initialization order.  They should shy away from topics which are more matters of opinion.  The correct bracing style and the use of Hungarian are classic topics that I don't think belong in a coding standard.  The best way to handle those is to require that people maintain whatever style the document was created with.  Don't intersperse your K&R bracing style with someone else's Allman.  And whatever you do, don't go changing already existing code to remove/add Hungarian notation or bracing, etc.

A coding standard which tries to stick to only those items that affect maintenance or cause bugs is much less contentious.  It's easy to defend and doesn't tend to step on toes.  When it does, you have good reasons to tell the violator why his code is likely to cause bugs or will be hard to maintain. 

What are your thoughts?  A lot of people are in favor of very restrictive coding standards.  If you're one, let me know what you perceive the benefits to be.


  1. Hi Steve,
    For my previous employer, we compiled our own coding standard for c# 2.0. Regarding the goals, check out this excerpt:
    "The coding guidelines have been written up for several reasons which should help writing high quality code that
    is easy to understand and maintain by (future) team members. We applly code reviews to validate code
    quality, so it is important that all members of a project use the same style of coding. Style in this sense means
    using common constructs, writing proper documentation and code comments, and organizing code to a common
    Although complying with coding guidelines may seem to appear as unwanted overhead or limit creativity, this
    approach has already proven its value for many years. Moreover, not all coding guidelines have a clear rationale.
    Many of them are simply choices we made at Ordina. Additional goals include:
    * Preventing common mistakes and pitfalls.
    * Preventing language constructs that are less comprehensive.
    * Promoting object oriented development."
    Dennis Doomen
    Aviva Solutions

  2. You're actually assigned to work on a Holy War?  :)
    What are you trying to achieve: readability or defect prevention?  If you just want readability, the Linux Kernel coding conventions are short and sweet.
    If you're trying to prevent defects, you introduce a lot more conventions. Joel Spolsky has a great article on using names to prevent errors,
    I like to see things like macros in CAPS, globals Capitalized, etc.  But the more standards you have, the more difficult it is to follow them.  Are you going to start filing defects against my code if I have a variable named arrayIndex instead of array_index?  Just because a practice can prevent bugs, doesn't mean your organization tends to have that type of problem.  Does the convention save more time that it costs?
    Perhaps you have a two tiered system.  A short list of absolute coding standards and an extended list of optional "best practices" to help prevent defects.

  3. Thanks for all the suggestions.
    Right now we're looking at a 3-tier system:
    1)  Things you must do (absolute coding standards) - you can't check in with these.
    2)  Things you should do - have a good reason when you don't.
    3)  Best practices - these are neither right nor wrong but patterns we recommend.
    Coding standards should be enforced via familiarity and code reviews.  Once the code is checked in, it doesn't make sense to file bugs to fix syntax issues.  Changing code for a non-bug just introduces real bugs.

  4. I would also suggest trying to lead by example.
    We try to make our new code look like the existing code, regardless of our opinion of its style.  Try to get there first and leave something behind for others to follow.