Do you have more then one person in the development team ? Then you may already know how important it is to have a consistent code style and formatting. Do you want to know how to enforce build failure if the code styling in the modifications is not consistent with the adopted style ?

This article tries to explain the basics around why it is important to establish code style / guidelines for a development team. It also explains how EditorConfig and dotnet format command can help to enforce the consistent code style.

What is Readability ?

Readability means the ease with which a reader can understand the written code (or any written text for that matter). Of course, readability is relative and same thing may be easy to perceive for a person, while it may be difficult to perceive for another.

What is maintainability ?

Maintainability is the ease with which a product can be safely and reliably modified / repaired / corrected to meet the (new or existing) requirements. This property is also not easily quantifiable.

Now, you may ask – why are we talking about maintainability ? Because readability affects maintainability too.

Thus, both readability and maintainability signify how easily developers can understand and modify codebase. And the readability / maintainability of code is not up to a standard level, it may have impact on overall quality and estimates and total costs.

Why is it hard to make produce readable code ?

Let’s see what are the things which make producing readable code difficult.

Alternative Coding Constructs

In programming world, there is one thing – which is its one of the major advantages as well as one of the major disadvantages. Basically, you can solve the same problem by using various programming constructs. for example, just for printing 10 numbers, we can

• either use any one of the iteration statement (while vs. do..while etc.).
• Or we also have option to use an IF Condition and a goto statement

Some of us may have personal preferences about these constructs. Also, often, new versions of programming languages come with additional syntactical sugars, providing even more ways for developers to write same code. For example, some of the syntax related decisions that a C# developer may need to take while writing code are:

• Top Level Statements vs Main method
• Minimal APIs vs Traditional MVC Style API Controllers
• Implicit usings vs explicit usings

Preferences About Code Beautification

But till now, we have only talked about variety of options available for writing code. A developer’s work is not limited to just writing a code that compiles and produces desired outcome. A developer’s work goes beyond that. The code should also be “readable” and “maintainable“.

There are many things which may affect readability of the code. Some of them are listed below:

• Indentation style (spaces vs. tabs, 4 spaces vs 2 spaces, start curly braces on same line or on next line etc.)
• Cyclomatic complexity
• Naming conventions
• Language Conventions
• Formatting rules

There can be many more things that can and will affect readability.

Perspective: Single vs Multiple Developer(s)

As stated earlier, every person will certainly have their own preferences about which style is more readable.

If there are more than one members in the team, it is almost guaranteed that the opinions will not match. If the opinions of developers working on same module / application do not match, then there is high possibility that the code that is written by those developers will not be consistent.

And due to this lack of consistency, the readability and maintainability will go for toss.

On the other hand, even if you are the single developer working on an application, this discussion is still relevant for you. If you go on long vacation or if you get transferred to another project, there will be (most probably) some other developer who will be taking charge or the code that you have written. And if the new person finds that the code is not “fairly” readable, then he may end up spending a lot of time in understanding the code.

So, when you are a single developer, the problem is how to set convey the code style to the new developer. Those expectations can be conveyed via code style document / profile.

That’s why, it does not matter if you are single developer or you are team of multiple developers. In both contexts, the readability of source code is immensely important.

Tools to solve this “readability problem”

First thing – I am not going to provide “silver-bullet” for this problem. In fact, I think it is hard to completely solve the issue. Let’s only talk about tools that can be provided and methodologies that can be applied to minimize this issue.

A team can decide to use common set of tools. Almost every organization follows this rule now.

Other thing that can be done is to have some team agreements in place. A team can agree on certain coding standards / constructs / styles. Traditionally, almost every project has coding style / conventions document.

In most cases, this document is enforced via code reviews and / or some tools like CodeMaid and ReSharper.

Code reviews is manual approach for enforcing the coding style and now a days, code reviews is not really most efficient way for this kind of enforcement for obvious reasons.

Automated tools like CodeMaid and ReSharper are better options as they will provide feedback faster and will also fix many issues automatically. These tools are more common for analyzing the code and fixing some issues based on coding standard profile configured in them.

In this article, we are going to talk about an approach to not only analyze and fix issues, but also to enforce the code style. By enforce, I mean that code should not build if it does not conform to the coding style document. And we are going to use EditorConfig file and dotnet CLI for that.

What is EditorConfig ?

EditorConfig file helps to maintain consistent coding style. Visual studio has built-in support (VS 2017 or later) for creating / updating this file. The image below shows how to add an EditorConfig file in a solution.

You need to right click on the solution and then select Add, which will open a submenu. From the submenu, select New EditorConfig option. This should create a solution folder with name “Solution Items” , if it is not already present. And a new file .editorconfig would be placed in that folder.

That file can be opened in visual studio for modifications. It has four sections – Whitespace, Code Style, Naming Style and Analyzers. Every section has many sub sections and many rules are present as a part of every subsection.

Going through all the rules would be very time-consuming activity. You also have option to start with some common rules and then keep on improving on the ruleset. You can refer the code styles from various open source repositories on GitHub to know about common rules.

The “dotnet format” tool

The dotnet CLI provides a dotnet-format tool. You do not need to install any tool for using this command, if you are on .NET 6 or above. You need SDK installed on the machine where you want to run these commands.

If you are on a earlier version of .NET then you can use the dotnet tool install command to install dotnet-format tool. The code snippet given below shows how this command can be used for various purposes.

Below is a sample output when I ran this command on one of my sample project:

How to enforce the coding style via pipelines ?

The dotnet format command can be executed via a build task. If you run the command given below , it will generate report of all the issues found during the verifications.

dotnet format –verify-no-changes –report issues.json

Most important thing is – this command will return a non-zero value indicating that the command has failed. So, the build pipeline can be configured to consider non-zero return value as failure.

Important Links

Below are some important links in case you want to know more.

• EditorConfig on GitHub
• dotnet format command
• EditorConfig from dotnet aspnetcore repository
• EditorConfig from dotnet runtime repository
• Coding Guidelines documents from dotnet repository

I hope you find this information helpful. Do you have any experience with what are some limitations of this approach ? Are you using any other tools for improving overall quality of the codebase ? Let me know in the comments.