Seven Steps to Quality Code – Step 4


This is step 4 in a series of articles, starting with Seven Steps To Quality Code – Introduction.

How often have we heard things like “Steve wrote that – I’m not touching it!” or “That came from the offshore team – it’s a mess”?  Often, this is down to a question of personal style.  The code in question may be perfectly readable and maintainable to the developer who wrote it, but not to anybody else.

If we want robust and maintainable (i.e. quality) code then a standard style, consistent across the whole team or organisation, is what is required.  If the code is always written in the same style, then developers can focus on functionality and correctness rather than being distracted by inconsistencies in coding styles.

As with the other steps, this isn’t a new idea,  It has long been recognised that some sort of corporate “Coding Standard” is useful.   This would perhaps specify common standards for all code – things like layout, formatting, casing, naming conventions etc.  Traditionally, if an organisation has a view on these things, lots of effort would be spent in devising the standard and creating a “coding standards” document hidden away on a server somewhere.   New developers typically have this document on a list of “documents to read” as part of their induction. In my experience, that’s usually as far as it goes.  The practicalities mean that enforcing the corporate standard is simply too difficult and so the code rarely, if ever, actually conforms to the standard.  Each developer uses their own view of “standard practice” and these views often differ widely.

In this fourth step, we are going to address these issues.  The approach is to discard the Coding Standards document and instead introduce our next tool – StyleCop.  This tool was originally developed to enforce standards on internally created code in Microsoft but was then released for public use.  In 2010, it became open source and is now available on the StyleCop CodePlex page.   In a similar way to Code Analysis/FxCop introduced in step 3, it analyses code against a set of predetermined rules.  The difference between the two tools is that Code Analysis looks at the compiled assemblies, whereas StyleCop looks at the contents of your source files.  There are some overlapping areas, but StyleCop will focus on what your code looks like, rather than how it behaves.

A sample of the things that StyleCop will report are as follows:

  • Incorrect casing of variables, method names, property names etc.
  • Incorrect naming conventions (e.g. use of underscores)
  • Missing XML comments
  • Non-standard XML comments (for example, read/write properties must start with “Gets or sets…”)
  • Incorrect spacing around operators, brackets, commas etc.
  • Missing curly brackets
  • Missing and superfluous blank lines

Like Code Analysis, rule violations are reported in the Visual Studio Error window, as shown below:

StyleCop Warnings

Also like Code Analysis, detailed explanations can be found by right-clicking and selecting “Show Error Help”. Unlike Code Analysis, individual rule violations cannot be suppressed.  This is not important with StyleCop as the rules are more objective and not prone to exceptions like Code Analysis rules.

It is possible to switch off a rule entirely, but I would strongly recommend not doing this.  My approach is to leave the rules in their default state.  This leads to a much simpler situation for ongoing configuration management as there is no configuration required by project, solution, developer or machine.  Additionally, there are rules that complement each other and work together “as a set”.  For example, the common practice of prefixing class level fields with an underscore is outlawed under StyleCop, but this practice is complemented by a rule that insists that these fields are preceded by “this”.

Some of the rules may seem a little strange at first.  The aforementioned rule about not prefixing with underscores being a good example if you have been used to this previously, using statements having to be inside the namespace being another.  However, it takes a surprisingly short period of time before the standard StyleCop format becomes “the norm” and non-compliant code is jarringly wrong.

The real beauty of using StyleCop is that it quickly becomes possible to see past what the code looks like (because it’s always the same) and see what it is doing.  Errors in logic or function jump out of the page in a way that is simply not possible when everyone codes to their own style.

Rules/Guidelines for Using StyleCop

These are similar to the guidelines for Code Analysis.

  • Stick with the default rule settings.
  • Incorporate StyleCop into your process. Configure it to run each time the solution is built. If you have an automated build, incorporate it there.
  • Always have the Visual Studio Error window visible.  You get immediate feedback on violations following a build (as well as build errors, compiler warnings and Code Analysis violations).
  • Fix violations frequently.  Fix them as they occur.  Don’t leave this as a task to be performed just before check in.
  • Always use the error help if the rule isn’t understood. There is often interesting commentary on the rationale behind the rule.  In the early days, it’s worth looking at the help even when you think you understand the rule.
  • Use GhostDoc.  StyleCop is hard work without it, GhostDoc becomes absolutely essential.
  • Persevere.  It can be daunting to see a single class with 600 violations, but this means there is massive scope for improvement in such a class and so the benefits and the feeling of accomplishment once it’s done will be worth it.

Once the use of StyleCop is embedded, you will be well placed to move on to step 5...