As a developer, I love to write code.  Getting involved with a problem, putting my head down, coming up a solution and getting immersed in implementing it is an awesome feeling.

I also enjoy reading code.  I like to look at a set of code and try to understand what the developer was thinking.  You can tell a lot about how a person thinks by reading their code.  To me, participating in code reviews is a lot of fun. 

I originally wrote these articles 6 months ago when I was about to launch a new service to review code (For details, go to http://www.codefrisk.com/).  I’m now much too busy to review code, but these articles might be of value, so I’m uploading them now.  I’ll be posting a set of articles about code reviews, best practices, coding standards…  Here’s the first article in the series:

Coding Standards – How to write a useful Coding Standard document

Coding standards are an agreement in a development team on how the code for an application will be structured.  They promote consistency and easier maintenance.    A well-written and enforced standards policy will reduce the time that it takes for new developers to feel comfortable with an application.

I’ve worked with many organizations over the years, most of which have some sort of coding standards documentation.  The needs of each organization are very different.  Some organizations sold their source code, so they needed to make sure there was a very high level of consistency.  Others were in regulated industries and needed to conform to various practices.   Others were small shops that didn’t see tremendous value in having standards.

The standards document had varying degrees of success.  Some negative factors in coding standards I’ve seen are:

• Aggressively guarded by one person
• Enforcing rules that were necessary in older technologies, but no longer hold relevance (Especially if they were burned by the problem)
• Too slim
• Too thick
• Too strict
• Begun, but never completed.
• Finished, but never enforced.

I’ve written a few coding standards docs and want to share what I’ve found useful, and what you should try to avoid.

First of all, if you’re the person tasked with writing the documentation, make sure that you involve the rest of the development team as much as possible.  You shouldn’t take the Moses approach; climb a mountain and come down with a set of commandments.  If the developers on your team aren’t consulted on the coding standards, you’ll see a lot of them not adhering to them.  These aren’t your coding standards; they are the teams coding standards.

Recognize that you aren’t writing a document with a stone and chisel.  Coding standards must evolve as your team has learned new techniques.  It’s also not uncommon to see coding standard docs that never get finished because the author feels the document must be 100% “complete” before they release it.  Take an iterative approach and get the document out as soon as possible and continue to refine it.  It’s impossible to get it all right the first, second, or even tenth time.  You’ll probably find that most code reviews will result in changes to the standards document.

Kick off a discussion for an hour or two and brainstorm with the development team about possible standards.  There will be contention.  If the team can’t come to an agreement after 5 minutes, table the discussion point for later.  If people have time to think about something, they will usually be able to justify or back off on their opinion.    The important thing is to limit the time of the discussion in the interests of getting an initial version within the same day.  Good developers will talk about coding all day.

Areas to discuss would include:

• Naming standards – Camel, Pascal, Hungarian, Dewey Decimal System?
• Documentation expectations – XML Documentation, when/where to put comments, class headers…
• Design Patterns that are expected to be used – Factories, Observers, Decorators…
• Automated Unit Testing strategy – TDD? Tool type, Code Coverage…
• Exception handling – Handling, Reporting…
• Use of constants/resource files – Yes, No?  One resource for the entire project, one constant class?
• Complexity limits for methods - > 25 is a lot of branches
• Data access methods - Stored Procs, Dynamic SQL, DataSets, ORM, Async, Transaction strategy…
• Common components to use – Enterprise Library, Log4net, Infragistics…
• Localization strategy -  Needed?  Roll your own or use .NET framework...
• Versioning – Versioning assemblies, strong name, signing, delay signing…
• Build strategy – Nightly builds, one solution or many solutions, creating references
• !Code Formatting

For the most part try to stay away from talking about code formatting.  Formatting standards inevitably come down to one developer’s preference over another.  Capable developers will be able to read the code regardless of how it is formatted. 

After you’ve had your discussion with the team, hole yourself up in your office/cube and write up the standards doc.  Unless you’re a dreadfully slow typist, this shouldn’t take more than 1 – 3 hours.

The important thing is to make sure you get feedback from your team on the document.  If they don’t feel involved and disagree with a particular piece, they will exhibit a little bit of passive-aggressive behavior and not adhere to the standard.

The Coding Standards document sets up expectations at code reviews.  It is a declaration of what is expected from a developer when they submit code.  Without some set of coding standards, code reviews can quickly become counterproductive.

Coding standard docs aren’t hard, aren’t intrusive, and are a valuable resource.  When there is a set of guidelines to use when coding, it is much easier to bring new developers into the project.  The benefits justify the one day of effort it takes to put one in place.

Wouldn’t you feel comfortable having your code reviewed by an expert?  Go to CodeFrisk.com to see how I can proofread your code at a reasonable price.