When you read a certain magazine or newspaper, you don’t have the feeling that the articles are written by a number of persons each having their own personalities and characteristics. When reading the first article, you can’t decide when looking at another article by looking at the use of words if it is written by the same person or not. The same strategy we see back at clean written code: it will show consistency throughout the solution. If applied well, you can’t tell that some class is written by one developer and another class by another developer.

What is actually the benefit of having all code written down like it is written by the same person? Note that we spent more time reading back code than we spend time at writing the code. If this is the case, you want fellow programmers to quickly grasp the main important things you want to achieve by the code you’ve written. One thing that helps with this is having the same coding style all over the same code base.

Coding conventions

We quickly touched in the section before what coding style is. This style can be captured in a coding convention, which is shared along the team. The team will agree upon these rules and try to respect them.

When looking at what typical lint tools do is that they will guard constructions that could lead to an issue. For example the lint tool will give a warning or error when using the following line of code in C++:

if (n = 10) {
 ...
}

The if (n=10) will always yield to true, since this is an assignment which will always be true. The lint tool will warn you for this construction and asks if you didn’t mean to check the fact if n is equal to 10 by writing down if (n == 10).

Besides checking for constructions that will protentional lead to errors, a tool can also check for naming conventions that are used within the team. A team can decide that method names always are written in CamelCase and local variables will always start with a lowercase letter (pascal case). Rules defined within the tool can verify this and give either a warning or an error when checking.

Types of check

So recapturing, we could have the following type of checks:

• Construction rules;
• Naming rules;
• Formatting rules.

Construction rules

Construction rules are rules that prevent using a construction that potentially can lead to issues within the written code. Like we saw before by the example where we tried to construct an if-statement, which was in fact an assignment is an example of a construction rule.

Besides adding code, it can be also be the fact that code can be left out. Unused variables or commented out code can be removed for example.

Naming rules

When describing if a method should start with a uppercase, lowercase, camel style, pascal style or whatever is defined within the naming rules. The naming rule specifies how language elements should be named.

Formatting rules

When it comes to how to indent lines, use spaces or align your code is defined within the formatting rules. For code reviews, a lot of teams use a maximum number of characters that can be used in one line. Long lines for example have the difficulty, even on large screens, that you have to do additional things to be able to show the original code and the changes that have been made.

Guarding your coding style

There are many ways to guard the coding style in your project. One of the easiest things to do, but also the most error prone one is by having written down your coding conventions in a document and let the team members during a code review check if one of them is violated. Since this is a manual operation one could easily miss code that is violating a rule.

The most error prone one is by having written down your coding conventions in a document and let the team members during a code review check if one of them is violated.

Another way is using your IDE to check for coding style violations. There are two ways the IDE can help you, either by giving a hint or a warning to the programmer when a coding style is broken or by actually giving a compilation error. Within Visual Studio you can use either “Code Style” within Tools->Options->Text Editor->C#->Code Style for this or add within a project or solution a .editorconfig file.

Another way is using your IDE to check for coding style violations

The third option is to use a lint tool to guard coding style. There are a number of tools that can be used to do this. Within .Net you can for example use the Roslyn Analyzers.

Use a linting tool to guard coding style

Putting the guard at the level of your IDE puts a check at a higher level, just where the developer is writing his or her code. When you check the violation of rules at compile time, this is just a step later. It can save time when guiding the developer at the point when the code is being written.

Putting your guards into place

We saw three places where we could add a guard to check our code style. You can put all guards in just one category, but just putting all into the category where you manually check the rules is error prone. On the other hand putting everything into an analyzer (both editorconfig or lint tool) can be very labor intensive to implement and maintain.

When automating things by using the editorconfig or lint tool, rules can be guarded by only one of the tools or both. The editorconfig file that can be used by Visual Studio is in my opinion better suitable for guarding formatting rules and maybe naming rules. Defining construction rules within a editorconfig file is much more difficult, where the analyzers already have predefined constructions that are used by numerous other developers. This means when an error in one of the analyzers is found, it will be probably fixed within the community.

If the rule doesn’t meet the rules you are using within your team, you can most of the times easily change the configuration of them or disable them if you don’t want to apply them.

The editorconfig file is quite easy to add and update (I’m planning to write another blog post that goes deeper into the use of these files), and the main benefit of it is that Intellisense within Visual Studio will either automatically update your code to reflect the rules or gives a suggestion to fix them. One of the this is for example if an accolade after a method should be put on the same line or put on the next line. So for example this:

private void MyMethod(int a)
{
  ...
} 

or this style:

private void MyMethod(int a) {
  ...
} 

Getting started

Looking at the various strategies, decide which of them you want to apply in your team when applying code rules. Having at least a set of rules and applying them will increase the change of having clean code into place. This will likely ease reading code, maintaining them when solving issues and adding new features to them. In the end it will lead to a higher quality of your software and the efficiency of your team.