Formatting For C#

What Does Formatting Mean?

Formatting is how your code looks, plain and simple. It is extremely personal and everyone has their own preferred rules for it. It is made up of numerous small decisions:

• How and when to use comments
• Tabs or spaces for indentation (number of spaces)
• Appropriate use of white space
• Proper naming of variables and functions
• Code grouping
• Patterns to be used
• Patterns to be avoided

Why is Formatting Important?

Why should we care about formatting? Isn’t it enough that our code works? Well, there are a couple of reasons to care about formatting.

• The first is consistency. Any large code base with multiple team members should look as if only one programmer wrote it. For example, programmer A likes double quotes in his code but programmer B likes single quotes. This can cause a headache for code check-ins and reviews. Once a format is decided with a team, everyone should follow it. This is not about preference. Rather, it is about writing clean and consistent code, exactly what professional software developers should do.
• Good layout has been proven time and again to make code more readable - and the time it takes to do it neatly always repays itself many times over in the future.
• When you want to revisit your code, proper formatting will take less time in finding any error/bugs.

What is dotnet-format?

Dotnet-format is a code formatter for dotnet that applies style preferences to a project or solution. Preferences will be read from a .editorconfig file, if present. Otherwise, a default set of preferences will be used. At this time dotnet-format can format C# and Visual Basic projects with a subset of the following options:

The dotnet-format global tool supports the core set of EditorConfig options*:

• indent_style
• indent_size
• tab_width
• end_of_line
• charset
• insert_final_newline
• root

[*] The option trim_trailing_whitespace is not supported. Currently insignificant whitespace is always removed by the formatter.

Also dotnet-format supports a subset of the .NET coding convention settings for EditorConfig.

How Can We Define Formatting Conventions in the .EditorConfig File?

Most of the rules for formatting conventions have the following format:

rule_name = false|true

You specify either true (prefer this style) or false (do not prefer this style). You don't need to specify the severity of the condition which you want to check before applying the checking style. For a few rules, instead of putting true or false as the value, you specify other values to describe when and where to apply the rule.

How To Install Dotnet-format?

The dotnet-format NuGet package is published to nuget.org.

You can install the tool using the following command.

dotnet tool install -g dotnet-format

How to Use?

By default dotnet-format will look in the current directory for a project or solution file and use that as the workspace to format. If more than one project or solution file is present in the current directory, you will need to specify the workspace to format using the -w or -f options. You can control the output by using verbose(-v option).

How Can We Use dotnet-format For Defining Checking Style For Code Written in c#?

Step 1: Open a command prompt and run the following command:

dotnet new console –n <folderName>

 Let's do a quick walkthrough:

dotnet new console –n <folderName>-- dotnet new creates an up-to-date folderName.csproj project file with the dependencies necessary to build a console app. It also creates a Program.cs, a basic file containing the entry point for the application.

Now, I am just modifying the code inside Program.cs and also adding one more file in this folder named “Calculator.cs”. You can see the code inside both files in following screenshots:

Calculator.cs:

Program.cs:

Step 2: Create .editorconfig file. Now, create a .editorconfig file inside calculator folder and put the following code inside this file:

You can find a list of rules from here:  https://github.com/dotnet/format/blob/master/docs/Supported-.editorconfig-options.md 

Step 3: dotnet tool install -g dotnet-format. Run this command in the following way:

Step 4: dotnet-format. Run this command in the following way:

Now, you can see the changes inside calculator folder’s *.cs files, before and after running the above command:

Calculator.cs

Program.cs

How to Include the Formatting Process in CI/CD?

We can write a bash script (on Linux/MAC) to check whether the code is following the required formatting or not. We can also write batch/PowerShell script (for Windows) with the same intent.

Now we can run this shell script as a part of the CI/CD process before building the code. If code is not formatted, this shell script will fail and the complete build process will also fail. Happy coding!