Bruno Peeters Technical Blog

In my previous blog post, I wrote about guarding your code style. Here I showed a number of areas where to look for when defining your teams common code style. Also a number of tools where briefly mentioned that could guard these styles. One of these tools is EditorConfig.

EditorConfig consists on both a definition file, with the fixed name .editorconfig, which describes the code style. On the other side you have an IDE that guards this defined style. There are a number of IDE’s supporting EditorConfig out of the box, like for example Visual Studio (starting from VS 2017) and Visual Studio Code. Also there are a number of IDE’s that are able to support it, by using a plugin.

Structure of an .editorconfig-file

To define the code guidelines, an .editorconfig-file consists of a number of sections. These sections define to which filetype the rules should be applied. This makes it possible to have one .editorconfig-file, where you define for different programming languages like C#, C++ or Java.

After the section you can have multiple key-value pairs. The key defines a certain rule, followed by an = and the value which specifies the behavior of the rule.

When making changes to the .editorconfig-file, Visual Studio automatically detect changes to it, without requiring you to manually reload it.

Throughout the file, you can start writing a comment by adding a ; or a #.

The EditorConfig specification within each version number of it a number of supported key-value pairs. Not all IDE’s have the same level of support of the available keywords. The developers of the IDE have to implement the support for each of the settings within their product. This means certain EditorConfig keyword can work in one IDE, but not in the other. This something to be aware of, when you work within a team on a same code base, but each of the developers is free to use his or her own IDE of choice.

Sharing the code style among the team

You can simply share the code guidelines within the team, by putting the .editorconfig-file under version control. Updates to the guidelines can also be reviewed, by creating a pull request for a change to the config-file. When developers get the latest .editorconfig-file, their IDE will also use directly those changes.

It might be needed, when a breaking style is introduced, that all developers update their branches a quick as possible to the latest state of the .editorconfig-file. However, in practice you normally see that code styles are defined in the beginning of the project and mainly stay static during the development of a project. Only small, non-braking additions to these styles are more commonly.

Sample .editorconfig file

Let’s have a look at how a simple .editorconfig-file, where we define these rules, looks like.

# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true

# C# files
[*.cs]

# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4

In the example above, you see at the first line a comment, since it starts with a #. By the use of the root-value, you can define if you want to inherit the rules form the higher directories or not.

By specifying the section [*.cs], you tell EditorConfig to use the settings below for all files that have the cs-extention.

A couple of styles are defined below the section, like indent_size and the value 4. Here you specify for example how much elements the line should be indented.

Creating your .editorconfig files

There are a couple of ways to create, edit or even generate .editorconfig-files.

Using a text-editor

Maybe the simplest way to create and edit .editorconfig-files is by creating such a file and open it with your favorite text-editor. The config files contain simple plain text and can therefore simply edited by such an editor.

Generate a .editorconfig file from within Visual Studio

If you have already defined your code style settings manually within the settings of Visual Studio, there is a way to export these settings to an .editorconfig-file. Simply go within Visual Studio to “Tools->Options->Text Editor->C#->Code Style”. Here you will find a button “Generate .editorconfig file from settings”. By pussing it, it will open a “Save as..” dialog, which allows you to define the name of the EditorConfig-file along with it’s location.

It will also easing with the more complex constructions like guarding naming rules, which can become quite complex when defining them.

Checking if the styles are guarded

When you’ve created an .editorconfig-file, you can be put the file in a directory along with the other project files and source code. Depending on it’s location, the EditorConfig is used within the IDE at a certain scope to guard the code styles. For example Visual Studio respects the code styles for all projects within a solution, when the .editorconfig file is put in the same directory as the solution-file is. When having different editorconfig-files at lower directories near the project file, you can tailor the code style per project by specifying the styles that are different from the common editorconfig-file.

Visual Studio will automatically detect changes to the definition file and will automatically apply them. This makes it fairly easy to check changes to your definition file.

On the other hand when issues occur, it can be quite difficult to debug your definition file, since there aren’t any tools or ways to detect issues. Most of the times it depends on your IDE if it shows issues within your definition file.

Within Visual Studio, EditorConfig styles go before the IDE settings. So when user defined IDE settings conflict with the EditorConfig styles, the latter one is leading. This assures the style the team agreed upon is guarded above local settings.

Limitations

Limitations can occur either on the side of EditorConfig or on the other hand on the side of the IDE which is supporting EditorConfig. EditorConfig supports a number of styles, so if you need a style that isn’t supported by EditorConfig you have to find other ways to guard this. On the other hand, EditorConfig can support a certain rule, but if your IDE doesn’t implement this EditorConfig you are also out of luck here.

Conclusion

I think using EditorConfig with being able to put it’s definition file .editorconfig in your repository, makes it quite elegant to share the common coding standard within the team. It prevents that all team members have different project settings. By having version control into place, all members using the same repository share automatically the same guard to check the coding standards it agreed upon.