Coding Guidelines

This is the sixth blog of a series of posts about the topics Continuous Integration and Continuous Delivery. It explains how important continuous integration is to deliver software in short iterations to the customer with a high quality standard.

Many companies have written coding guidelines for the development which define naming, layout, commenting and a lot of other conventions. Even Microsoft has a couple of MSDN articles about coding conventions and design guidelines.

Coding guidelines are really important for the readability of the code and they can reduce the maintenance effort because the developer understands the code more quickly.

Many companies invest in writing documents about coding and design guidelines but the code does not follow most of the defined rules and the different components and classes have a completely different style. Just a document does not improve the code quality. The developers have to know the content of the document and have to follow it. The code has to be reviewed on a regular basis.

Usually, the guidelines document is just stored somewhere on a SharePoint or file share. It is also most of the time not up to date because another version of the programming language has been released. The new language features are not described or parts of the document are already obsolete.

This problem can be solved by using a tool like StyleCop. StyleCop checks during the build process if the code follows the defined rules. It can be checked, for instance, if all public methods are commented or every if-block is within curly brackets. The StyleCop rules can be defined instead of writing and updating the coding guidelines document. If the StyleCop rules are checked during the development process, some important time during the review can be saved. The reviews can focus on the architecture and design of the components instead of checking the style and naming conventions.

There are two ways to check StyleCop rules during the development process. Either via check-in policy or integrated into MS build. I would recommend to use the MS build integration because the check-in policy has to be installed on all develop machines and have to be kept up to date.

Integrate StyleCop into MS Build:
After downloading and installing StyleCop, there is a MS Build target in the installation folder:

StyleCop\<version>\Microsoft.StyleCop.targets

Just copy the file and check it in your source control. After that it can be referenced relatively in order to work on all developer machines.

<Import Project="..\StyleCop\Microsoft.StyleCop.targets" />

If the StylCop target is integrated in the MS Build, every violation is shown as a warning. In case you want to ensure the rules this might be not enough. I have seen projects with thousands of warnings in the build process. A warning is indeed not an error and the assembly can be still compiled but there are reasons why warnings are shown. That is why they should not be ignored. One possibility is to enable the build option "Treat warnings as errors". In combination with gated builds code cannot be checked-in anymore which do not fulfill the StyleCop rules.

But there is one big disadvantage in that approach. The developer cannot test easily changes on the code anymore because every time the violated StyleCop rules make the build fail. If, for instance, a new public method has been added and is not commented yet, because it is not finished completely, this code cannot be compiled and tested. That is the reason why I would enable this option just during the continuous integration build and disable it on the local machine. This can be done using different Configurations like in the following project file:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Local|AnyCPU' ">
  <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'TFS|AnyCPU' ">
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>