Developing Your Team Standards

One of the most common chores in any development team is establishing an agreed set of standards for use within the wider development group.  Typically, the team lead is responsible for either contributing directly to – if not solely responsible for – the authoring of a standards document that defines how your deliverables are shaped.

The most common scenarios I’ve seen are when a new Technical Team Lead has been appointed to the role (or been press-ganged into it) and a hospital pass is handed to that lucky candidate to own the task of getting the standards up to date, implementing them, or in more extreme cases, writing them from scratch.

I’ve found myself in this situation on more than one occasion and it is a completely overwhelming prospect when there is little or nothing to start from.  In this post, I will give a quick run-down of the key things you should include in your standards documentation and provide you with a working sample that you can adapt and improve as needed.

Starting From Scratch

Starting from scratch is probably the most intimidating position to be in.  You will often be lumped with this problem if the team is new, or if you are new to the team and no one has bothered to get around to it yet.

If you need to build out your standards from the very beginning, here are a few questions and considerations you need to address:

• Architecture: Classic or SOA? What layers should you generally have (e.g. presentation, data access, business logic, security, etc.)?  What clients does your business usually target (e.g. thin, fat, mobile)?  What integration concerns do you need to standardise?
• Technologies: What code is accepted / disapproved? What data storage and retrieval technologies should you use?  What scripting frameworks?  What languages?
• Tools: What testing frameworks should you adopt?  What about mocking? What version control systems and policies do you have in place? Continuous Integration?
• Documentation & Support: What are your minimum documentation expectations? How should your code be commented / documented?  Do you use documentation generators (e.g. Sandcastle, Live Documenter)?  What are your peer review expectations?  Who needs to be considered at handover when coding is complete and ready for delivery?

Updating Existing Standards

Being tasked with updating your company’s existing standards is a much more problematic situation.  The existing standards may either have evolved or stagnated over time and may not, in their entirety at least, reflect the true nature of your current development landscape.

Standards Review Process

The trouble is in the sorting of which content should remain, which should be modified and which should be removed altogether.  Start by identifying those standards that are completely obsolete or irrelevant to your current work; unsupported frameworks and languages, obsolete tools or unneeded documentation requirements.  Once this housekeeping task is taken care of, you can start on the more challenging part of adding new content in.  Pick your top problem area and define a workable approach to eliminate or minimise the impacts from that area.  After a couple of iterations, review how that standard is working and refine it.

When you feel that your team is operating well on this functional area, pick your next performance issue and repeat the process.

Documentation Isn’t Standards

It is quite common, especially in larger organisations, to have explicit provisions for various documents included as part of the team’s development standards.  Different people have different views on this topic, but my personal view is that documentation does not constitute a development standard; it is part of your process.

There are no doubt times when you need to supply a solution architecture document, design document or some other written artefact, but this is most often an internal requirement and does not affect how the actual product is designed and coded.  As mentioned before, unless it adds direct customer value, it isn’t really needed.

Your team may have some procedural requirement that outlines all the written material that is expected for a given deliverable, but this is effectively meta-content that only supplements the product – it doesn’t underpin it.

Don’t standardise your documentation deliverables unless (and even here I’m not that convinced of the need) there is a direct customer benefit and the standard can be scaled to both small and large solutions.

10 Commandments

As a pretty good rule of thumb, your full standards document will probably grow and evolve to become something of a behemoth.  You can expect your new developers to read this a total of once while they are still

1. Full of enthusiasm about starting with a fresh new company and are eager to impress
2. Bored out of their brain while they ramp up their understanding of how your team works

After this, you can expect your full standards document to be referred to in about one in every 100 cases.  This is normal (unless you run a code dictatorship, in which case you have bigger problems than whether your compliance rates are 100%).  It is because of this that you should have a standards 10 commandments list – preferably in soft copy (e.g. on your team’s SharePoint site or similar) that is easily found.  These ten commandments should summarise – in bullet form – as briefly as possible what your top ten minimum expectations are.

An example might be:

1. Code must be checked in to version control at the end of each week at a minimum and must not break the build.
2. Unit tests must accompany all complex code and should ideally drive the design of the behaviours they test.
3. JQuery is to be used as the accepted JavaScript framework in all web applications.
4. Code should have full XML comments such that they are sufficiently descriptive when documentation is generated from it.
5. Hungarian notation will summon the four horsemen of the apocalypse and should therefore be avoided at every cost.
6. Never write from scratch in JavaScript that which can be found in a stable, supported jQuery plugin.
7. Include only those features that have been explicitly asked for by the customer.
8. Major features cannot be released without first passing a peer review.
9. Business values and variables should never be hard-coded under any circumstances.  Offenders will be exiled to supporting IE6 for the rest of eternity.
10. HTML should never be rendered explicitly through code.

A list of key concerns such as this doesn’t undermine your larger standards document; nor does it replace it.  It is a quick reference so that developers can get an immediate grasp of your expectations around delivery.  If further information is needed, the standards document is where this should be found.

Baseline Standards Document

Having outlined all the considerations for writing a good standards document, it seems almost unfair to then expect you, dear reader, to then go off and write the whole thing from scratch.

Start by having a look at this development standards baseline document and see whether it might serve as a good starting point for your own internal documentation.  This document is written with Microsoft .Net shops in mind – particularly web application producers.  However, it should be easily adaptable for any development situation.

Much of the content is taken from the Microsoft Coding Guidelines site, with business-specific content prepended.

Hope this helps.  Enjoy.