Great content delivered right to your mailbox

Thank you! Check your inbox for our monthly recap!

In this blog post, I will share with you how we made sure that every piece of new code respects our set of good practices.

To do so, I will start by defining what are conventions. After that, I will explain why we use them. Then,  I will talk about why they are hard to implement and finally I will show you how we enforce our conventions here at Sherweb.

 

What Is a Convention?

First off, let us start by defining what a coding convention is. According to Wikipedia, here is the definition for coding conventions:

“Coding conventions are a set of guidelines for a specific programming language that recommend programming style, practices, and methods for each aspect of a program written in that language. These conventions usually cover file organization, indentation, comments, declarations, statements, white space, naming conventions, programming practices, programming principles, programming rules of thumb, architectural best practices, etc. These are guidelines for software structural quality. Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier

There are some elements of that definition that I do not agree upon. For example, the part that says that a convention is a set of guidelines that programmers are highly recommended to follow. However, in reality a coding convention is like a contract that the programmer must respect. Otherwise, the codebase will be a complete anarchy. Therefore, here is a modified definition that I find to be a better fit in our context.

Coding conventions are a set of rules that applies on programming style, practices, and methods for each aspect of a program. These conventions usually cover file organization, indentation, comments, declarations, statements, white space, naming conventions, programming practices, programming principles, programming rules of thumb, architectural best practices, etc. These are guidelines for software structural quality. Software programmers have to follow these rules to help improve the readability of their source code and make software maintenance easier”

 

Why Use Conventions?

As developers, we all know the importance of a uniform coding style. It facilitates our lives when we are reviewing a colleague code, when we start working on someone else’s code or even when we try to read some legacy code. As long as we have a common set of rules, it is easier to read and understand what is in front of us. As a rule of thumb, we should assume that we are working on someone else’s code 90% of the time.

 

Why Are They So Hard to Enforce?

As programmers, we experienced different conventions (depending on the school we graduated from, programming languages we learned, enterprises we worked for, projects we worked on or even managers we worked under). Since we share different backgrounds, it is normal to have different opinions on what is the best set of rules we should follow.

So, why are they hard to ensure?

  1. Some people may not agree with them, so they don’t enforce it
  2. Large set of rules might be hard to remember
  3. Manual checking is prone to human error (code review, pair programming, etc.)
  4. Lack of time!

These are definitely the four main reasons why it is hard to enforce coding conventions.

As you can see below, traditional solutions for enforcing coding conventions are far from perfect, as they do not fix any of the four reasons listed above.

 

Traditional Solution

A traditional solution to enforce conventions is to reject any pull-request that does not respect it. However, this will lead to delays, frustrations and will almost certainly be “bypassed” during rushed projects.

The code review is the last safety net to catch any code that do not respect the set of rules. It is a heavy burden for the reviewers, instead of having all their focus on finding bugs, they need to think about the conventions too.

Pros:

  • Great way to teach conventions

Cons:

  • Reviewer must remember all the conventions
  • Reviewer can’t focus only on finding bugs
  • Can lead to multiple back and forth
  • Can leak unconventional code into production code (human error)
  • Reviews take longer

What if we could catch these errors before pushing the code?

  • With pair programming?
  • With a Done-Done checklist?

Sadly, the pair programming solution and the Done-Done checklist have the same problems.  They both rely on human activities and as said before, humans are dumb, and they make errors.  What about state-of-the-art solutions?

 

Modern Solutions

We live in an era where there is an app for everything. There should be a tool for that single purpose… Guess what, there is one 😉

I will quickly present you two tools that we use here @Sherweb to ensure our coding conventions.

StyleCop

Stylecop analyses C# source code to enforce a set of style and consistency rules.

 

How we Enforce Coding

 

With this tool, you can select a set of rules, which will be enforce at compile time. We actually use StyleCop in all our projects.

Pros:

  • Open source
  • Enforce a set of style and consistency rules
  • No human errors
  • Doesn’t compile when a rule isn’t respected
  • Very large set of available rules
  • No plugin needed, simply imported as a NuGet
  • GUI to manage rules
  • Can be included in your CI tool

Cons:

  • For C# only
  • Custom rules can be hard to setup

ReSharper

We use ReSharper for many things; it really is a wonderful productivity tool.  It even includes a code inspection feature that help us find and correct our code to match our coding conventions.

 

How we Enforce Coding

 

It is also possible with ReSharper to set custom rules that are very specific to your reality.

Ex. We wanted to force our people to use our own Time library instead of the one provided by the .Net Framework. To do so, we simply created a new set of rules in ReSharper.

 

How we enforce coding

 

 

By doing so, every time someone uses the wrong implementation in his or her code, it is flagged as an error in VisualStudio. R# will even propose to use the appropriated implementation as a Quick Fix.

Here is a list of the pros and cons for ReSharper:

Pros:

  • Awesome productivity tool (@JetBrains: still waiting for my sponsorship 😉)
  • Can create custom rules specific to the domain
  • No human factor
  • Doesn’t compile if a rule isn’t respected
  • Very large set of available rules
  • Code cleanup feature (applies the rules automatically)
  • GUI to manage rules
  • Can be included in your CI tool

Cons:

  • Paid subscription

What About Other Programming Languages?

There are plenty of tools for other languages too.  Here are a few examples, with their respective languages:

  • CheckStyle (Java)
  • ESLint, JSHint (JavaScript)
  • Phlint, CodeSniffer (PHP)

For a more exhaustive list, you can go here.

Next Steps

Here is a list of rules that we are planning to add to further improve the quality of our code base.

  • Dependency analysis rules
  • Clean architecture analysis rules
  • Code smells analysis rules (something along the line of the CleanCode R# plugin)

To Conclude

As we just saw, it is excessively easy to use good tooling for rules and styles to have to rely on clumsy and puny human.

Written by Julien Aspirot Software Developer @ SherWeb