The importance of automated coding standards

There are lots of things we all know, as developers, we should do. These same things are things we likely never do.

Documentation, common file naming conventions, a consistent way of structuring code files.

Sometimes we start a new project and go full steam ahead into a set of proposed 'best practices'.

Public methods are documented, properties come before methods in code files. Everything is wonderful.

Then the curse of the busy software developer strikes.

New methods are added to fix an urgent bug and aren't documented. A rapidly thrown together class breaks numerous pre-defined coding standards the team agreed on.

It's all done for good reason, but it soon makes a mess.

New developers join the team and see a hodge-podge combination of personal preferences and differences. Seeing that they dive in with their own best practices and the confusion in the code base grows.

I'm sure we've all seen code bases like this out in the wild, but I can promise you there is a better way.

Two practices to beat the curse

There are two things I have started doing in EVERY SINGLE codebase I work on. I even have a repo in my Git account that is the base structure for every new project I start.

1. Stylecop

Stylecop is one of the best free tools I've found as a dotnet developer.

If you haven't heard of, or seen, Stylecop go and check it out right now. I mean it, right now. Here's a link to save your Googling.

Thanks for coming back.

To pluck some content straight from the Stylecop Github page.

"StyleCop analyzes C# source code to enforce a set of style and consistency rules."

Doesn't that sound a lot like the problem we are trying to solve?

What Stylecop allows you to do is define a set of rules that your code must meet. These aren't necessarily functional rules, but rules around styling and code layout.

For example, out of the box, it will ask for all public properties/methods/constructors/classes to be documented. If a method isn't documented, there will be compiler warnings.

However, the real beauty arrives with the configuration. Simply creating a stylecop.json file within the project files allows the tweaking of the default rules.

{
  "$schema": "https://raw.githubusercontent.com/DotNetAnalyzers/StyleCopAnalyzers/master/StyleCop.Analyzers/StyleCop.Analyzers/Settings/stylecop.schema.json",
  "settings": {
    "orderingRules": {
      "usingDirectivesPlacement": "preserve"
    },
    "documentationRules": {
      "companyName": "James Eastham",
      "copyrightText": "------------------------------------------------------------\nCopyright (c) {companyName}.\n------------------------------------------------------------",
      "xmlHeader": false,
      "documentInternalElements": false
    }
  }
}

This file is ensuring the using directives are placed OUTSIDE of the namespace (by default they are inside a namespace) and that copyright text is added to the top of every source file.

2. Warn as errors

Combined with the Stylecop code analyzers, enabling warn as errors as standard ensures that code can't be released until any styling errors are resolved.

One of the first senior devs who took me under his wing really drilled that point home. A warning is still a problem and should be looked at, not just swept under the rug and ignored.

I was a firm believer in warn as errors even before using Stylecop. Coupled with the code analysis and it truly does have a positive effect on code quality.

To enable treat warnings as errors, it's as simple as adding the below section to your csproj file.

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
   </PropertyGroup>
</Project>

Be warned. The first time I did that on a pre-existing codebase the world imploded. There were a lot of errors.

However, once caught up or when starting a new project, the benefits quickly rear their heads.

If you want to have a look at my standard base repository, then you can check it out here. I'm going to a bit more of a deep dive into this repo structure soon.