29,847 reads

How to Set up a Formatting Standard in Your Code Editor (And Why You Should!)

by Daniel GeneziniJanuary 8th, 2023

Too Long; Didn't Read

The EditorConfig file is used by editors and IDEs to define editor preferences for the project. Without it, IDEs and editors will use their general configuration, causing divergences in the files edited on them. In this post I'll show how to maintain a standard for everyone who works in the code, no matter the editor used. In the next post, I'll talk about how to enforce these (and other) rules on build and in the continuous integration pipeline.

featured image - How to Set up a Formatting Standard in Your Code Editor (And Why You Should!)

When working with other people and multiple editors/IDEs, it is common to have different editor settings, losing consistency in formatting styles of the code. For example:

Using tabs/spaces and different sizes of indentation, making your code harder to read;
Using different encoding between files, causing hard to find bugs at runtime (showing invalid characters) and breaking automated tests.

In this post I'll show how to maintain a standard for everyone who works in the code, no matter the editor used, and in a next post I'll show how to enforce these (and other) rules on build and in the continuous integration pipeline.

Enter the EditorConfig file

Many editors and IDEs support the EditorConfig file by default, and others have plugins to support it. Here are some:

Visual Studio (Built-in);
JetBrains Rider (Built-in);
GitHub (Built-in);
VS Code (Plugin);
Vim (Plugin);
Emacs (Plugin);
Sublime (Plugin);

It has a default name of .editorconfig and is an INI file where sections are filename filters, for instance:

[*.cs] for .cs files;
[scripts/**.js] for javascript files inside the scripts folder and subdirectories;
[{package.json}] for the package.json file only.

More details here

The EditorConfig can be put in any directory and be overridden by EditorConfig files in child directories, but for better visibility, they should be in the same directory as the .NET solution file.

Adding an EditorConfig to your project

To include an EditorConfig to your project, just create a file named .editorconfig in the same directory of your solution file (.sln) with the content below.

# Top-most EditorConfig file.
root = true

# Section for C# files
# All rules below apply only to .cs files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_style = space
indent_size = 4

# New line preferences
end_of_line = crlf
insert_final_newline = false
trim_trailing_whitespace = true

# Charset preference
charset = utf-8

This file set these rules:

root: No editorconfig file in parent directories will be read;
indent_style: Indentation should use space;
indent_size: Indentation should use 4 space characters;
end_of_line: Lines should end with CR+LF characters;
insert_final_newline: Do not automatically insert empty lines at the end of the files;
trim_trailing_whitespace: Empty lines should have no space characters;
charset: Files should be encoded with UTF-8 format.

More details here.

⚠️ GIT can change the line ends to LF on pushes to the repository and change it back to CRLF on checkouts. Then, the end_of_line settings can be safely set to CRLF. GIT for Windows suggests this configuration by default at installation. Details on how to configure are here.

⚠️ UTF-8 with BOM is not required nor recommended, according to the Unicode standard. More here.

ℹ️ In .NET, the EditorConfig file can also be used to define analyzers rules and severities specific to the .NET environment. In a next post, I'll show how to configure these rules.

Appling the new formatting rules to code

When we change the formatting rules for an existing project, the changes are not applied automatically. We need to manually trigger an auto-format.

Visual Studio

First, we have to include the Format document fixer to a Code Cleanup profile.

1 - Navigate to Analyze > Code Cleanup > Configure Code Cleanup.

2 - Include the Format document fixer for the profile you wish to run on save.

3 - On the menu, select Analyze > Code Cleanup > Run Code Cleanup (Yout Profile) on Solution.

⚠️ Visual Studio's format document doesn't change the file encoding. You have to use the dotnet-format or another tool for that.

VS Code

VS Code doesn't have a feature to format all files at once. You have to use the Format Files extension.

1 - Install the Format Files extension.

2 - Navigate to View > Command Palette or press Ctrl+Shift+P.

3 - Select the Start Format Files: Workspace or Start Format Files: From Glob option.

JetBrains Rider

Select Code > Reformat Code or press Ctrl+Alt+Enter.

Format on save

When we create an EditorConfig file, the supported editors will also use the configurations for their auto-format features.

Here I show how to enable the auto-format on file save in some editors.

Format on save in Visual Studio

Visual Studio 2022 doesn't have a format on save feature, but it can run a Code Cleanup on save. This way we can configure a Code Cleanup profile to run a Format document and use it on save.