Code Focused

Enforce Standards via EditorConfig Files

EditorConfig Files are new to Visual Studio 2017, and they're one way to get all the developers coding on the same page, so to speak. Here's a quick look.

I probably hate your code. Not the logic or the data management parts; those are fine. What I hate is that you indent every source code line in increments of three space characters, instead of using tabs. You know, the way that Kernighan and Ritchie always meant things to be.

When you work on lone-wolf projects, none of these quibbles matter. You can enforce any whitespace and indentation standards that you want. But as more projects move to open source platforms, to be maintained by developers using varying coding standards on OSes with differing line-ending rules, there are bound to be conflicts. Welcome, EditorConfig files!

EditorConfig files are new to Visual Studio 2017, but they have been available on other platforms for years. The simplest way to use the feature is to drop a file named .editorconfig in your source code folder, fill it with the right stuff, and start editing your code with standards enforced. Any editor that supports EditorConfig files will load in the settings and obey its mandates.

EditorConfig files are INI-style text files, a 1980s configuration format that just won't die. Each bracketed section identifies a filename pattern, and the key-value pairs within each section define the rules to apply to matching files. Comments begin with the # symbol:

# ----- Indicates the top-most EditorConfig file
root = true

# ----- Default rules for all filename matches
[*]
end_of_line = crlf
indent_style = tab
indent_size = 4
insert_final_newline = true

# ----- Rules for files matching a pattern: CSS in the styles folder
[styles/*.css]
indent_style = space
indent_size = 2
charset = utf-8

# ----- More complex names are possible: text and markdown files
[*.{txt,md}]
indent_style = space
indent_size = 4

The standard keys cover indentation, line endings and whitespace. Table 1 documents the purpose of each official key.

Table 1: Standard Keys for EditorConfig Rules
Key Name Description indent_style Set to "tab" or "space." This and all other keys also support an "unset" option, which tells the editor to use its default implementation instead. indent_size An integer that indicates the number of space-columns to use for each line indent level. tab_width This integer defines the space-column equivalent for each tab character. If missing, the value of indent_size is used. end_of_line Choices are "lf," "cr," or "crlf." The "crlf" setting is normal on Windows systems; "lf" is common in Linux and macOS environments. If your code base is from a Mac, your Windows editing environment could use "lf" so that cross-platform file edits don't mess up line endings. charset The character set can be "latin1," "utf-8" or other options specific to 16-bit Unicode files. trim_trailing_whitespace When set to "true," any whitespace dangling at the end of each line is purged. insert_final_newline If you like to see a blank line at the end of your files, set this to "true." root Multiple EditorConfig files can reside in a hierarchy or along recognized configuration paths. This key says, "Let this config file be your last."
Key Name Description
indent_style Set to "tab" or "space." This and all other keys also support an "unset" option, which tells the editor to use its default implementation instead.
indent_size An integer that indicates the number of space-columns to use for each line indent level.
tab_width This integer defines the space-column equivalent for each tab character. If missing, the value of indent_size is used.
end_of_line Choices are "lf," "cr," or "crlf." The "crlf" setting is normal on Windows systems; "lf" is common in Linux and macOS environments. If your code base is from a Mac, your Windows editing environment could use "lf" so that cross-platform file edits don't mess up line endings.
charset The character set can be "latin1," "utf-8" or other options specific to 16-bit Unicode files.
trim_trailing_whitespace When set to "true," any whitespace dangling at the end of each line is purged.
insert_final_newline If you like to see a blank line at the end of your files, set this to "true."
root Multiple EditorConfig files can reside in a hierarchy or along recognized configuration paths. This key says, "Let this config file be your last."

Platform-specific settings also exist, though as with the standard keys, not every editor or tool supports all settings. Visual Studio adds a few dozen of its own keys, all of which trigger specific standards within various files. The dotnet_style_qualification_for_field key, for example, indicates whether the "this" prefix (or "Me" in Visual Basic) should appear on references to class-level fields in your code. The language-specific csharp_new_line_before_open_brace key indicates which C# multiline constructs should push the opening curly brace onto a line all its own. Of course, this setting is really superfluous, because every opening curly brace on a block statement should appear on a line all its own, not indented from its associated statement. You're welcome.

One downside to EditorConfig files is that their settings only impact new content. Any source code lines that existed before the EditorConfig file was added or modified remain untouched, with no alterations in their whitespace, indentation or platform-specific preferences. (Line endings will probably change on updated files, because they're global to a file.) This don't-alter-the-past mindset also impacts file and project templates. If you set your EditorConfig file to enforce tabs within indents, adding a new C# Class file to your project will still generate a new file filled with space-based indents, because the underlying template was designed with embedded spaces.

If you use an unsanctioned editor to update files outside of Visual Studio, there's a good chance it supports EditorConfig. Some tools, like BBEdit, have support for these files built right in. Other editors, including my own preferred workhorse, Vim, require that a free extension be installed before they recognize the files.

You can find out more about the design and goals of EditorConfig files on the official project Web site, editorconfig.org. Documentation on the Microsoft-specific settings appears at here.

About the Author

Tim Patrick has spent more than thirty years as a software architect and developer. His two most recent books on .NET development -- Start-to-Finish Visual C# 2015, and Start-to-Finish Visual Basic 2015 -- are available from http://owanipress.com. He blogs regularly at http://wellreadman.com.

Featured

  • Purple Nebula Graphic

    Open Source Uno Platform Takes Xamarin.Forms Mobile Apps to the Web via WebAssembly

    The open source Uno Platform announced new integration with Xamarin.Forms that lets developers take existing XF mobile apps to the Web, using WebAssembly.

  • Swirl

    Blazor WebAssembly Not Ready for .NET Core 3.0 Prime Time

    The much-anticipated .NET Core 3.0 milestone release is shipping in five days, Sept. 23, but it won't include a stable Blazor WebAssembly.

  • Visual Studio 2019 16.3 Preview Adds .NET Core Database Profiling

    Microsoft shipped Visual Studio 2019 16.3 Preview 4, adding database profiling for projects based on .NET Core, which is coming out in a big v3.0 milestone release next week.

.NET Insight

Sign up for our newsletter.

Terms and Privacy Policy consent

I agree to this site's Privacy Policy.

Upcoming Events