Coding Standards

After volunteering earlier in the year to document the coding standards for the development team, I have eventually managed to honour that commitment. It certainly hasn’t been an easy task either. It wasn’t until I started that I realised just what a substantial task I had volunteered myself for.

We have several applications for which we are responsible. These are mainly web and mobile applications. The primary programming languages are C# (for all the Web API RESTful services), VB.NET (for the legacy back-office enterprise application) and HTML / CSS / Javascript (for the mobile apps).

I focused primarily on documenting C# and Javascript. It is the long term goal to eventually re-write the legacy VB.NET web application, and move the team entirely over to C# development, so I didn’t want to waste any effort documenting coding standards for a language that we will eventually stop using.

The most difficult part of drafting a coding standards document is to what level should you go? Too much detail and you risk stifling creativity by slavishly following the numerous coding standards to the letter. Too little detail and you risk having code that is inconsistent by having insufficient guidance as to what constitutes acceptable code.

So I tried to strike a balance between these two competing demands to create a document that allowed the developer to be creative whilst simultaneously giving enough guidance so as to create consistent code that conformed to best practice.

The document covered areas including naming conventions, layout and organisation, language features, best practices, architecture and design. The aim of any coding standards document is to bring consistency, so that code produced by developer A will look the same as that produced by developer B. Even though the actual code that either developer produces will be different, it should look the same in terms of the criteria mentioned above.

The document will be a perpetual work in progress. Rather than a static document that rarely gets updated, I’m aiming for a document that is fluid and can can (and should) be updated when necessary.

Another question that arose is who should own the coding standards document, and how should it get updated? Currently, yours truly owns the coding standards document, but it will be updated by consensus. If something contained within the coding standards document needs to be updated, then this will be agreed by the team as a whole, and not just enforced by a single individual.

The first draft of the coding standards document has now been released for the rest of the team to provide feedback, and any updates made as necessary. After that, the document will be put into production and updated thereafter whenever required.