How to Edit Consistently Using EditorConfig

When working with other developers on a project, editor and IDE differences, whilst not fatal, can be annoying, even violate group coding standards.

Whether it’s tabs versus spaces, adding a trailing newline at the end of a file, removing trailing whitespace at the end of lines of code, these issues aren’t critical to code quality. But having a simple, consistent standard in place, makes code:

• Cleaner
• More consistent
• Easier to read

This tutorial shows you how to use the EditorConfig file format to ensure consistency across editors and IDEs.

At this stage you may be spitting your coffee over the screen, or calling me any number of names. That’s fine. I can neither see nor hear you.

But seriously, I’ve come to believe, after nearly 20 years developing software, that these little things do matter. I’ve come to believe that when they’re inconsistent, even erratic, they detract from code quality, create friction, and result in slower development time.

It shouldn’t be hard for any organization to agree upon a standard and then enforce it. It also shouldn’t be hard to do this consistently, regardless of the IDE or editor which any developer in the organization prefers to use.

Gladly, in a recent project, I came across a file format, one supported by a wide range of the editors and IDEs in use today, which make this trivial to implement. It’s called EditorConfig. First, here’s how the project describes itself:

EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.

Given that it’s a file format, based on the INI file format, once you or your organization’s decided on your conventions, all you need to do is:

1. Create a new .editorconfig file in the root of your project repository
2. Configure the options you need
3. Add it under version control

Then, whenever any of your developers checks out the code, or pulls the latest changes, they’ll get the file and their IDE will opt to enforce the standard. Now let’s look at the options on offer.

What’s handy is that you can likely start using it straight-away, as it’s supported by the major IDE and editor vendors. Here’s a short list:

• JetBrain’s IDEs, including PhpStorm, and WebStorm
• BBEdit
• Atom
• Sublime Text
• GitHub
• Emacs & Vim
• Brackets
• Coda
• Eclipse & NetBeans
• gEdit, jEdit, & Notepad++
• textmate
• Visual Studio
• Xcode

Hopefully, by this stage, I’ve whet your appetite to get started. Here’s the options which are currently supported.

• indent_style: whether to use tabs or spaces
• indent_size: the number of columns used to indent or the width of soft tabs
• tab_width: the number of columns used to represent a tab character
• end_of_line: The character which represents a line break. Options include lf, cr, or crlf
• max_line_length: Whether to forces hard line wrapping after a specified line length
• charset: the character set to use for saving files
• trim_trailing_whitespace: whether to remove trailing whitespace at the end of lines
• insert_final_newline: whether to add a newline at the end of a file on save
• root: Stops .editorconfig files search on current file if set to true.

The format isn’t, at least not yet, super extensive in the features which it supports. But it’s growing. I’m assuming the section entitled “Ideas for Domain-Specific Properties” is an indication of what may be coming, as it has options like quote_type, curly_bracket_next_line, and indent_brace_style.

A really handy feature of the format is that if a setting isn’t explicitly declared in your .editorconfig file, the plugin in your editor or IDE should use it’s default setting.

What’s more, when written well, .editorconfig won’t override the settings if you don’t want to use them. This may seem counter-productive, but it’s nice to have a choice.

Now let’s look at a default configuration. I’ve provided an annotated one below.

root = true

; applies to all files
[*]
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

; applies only to PHP files
[**.php]
indent_style = space
indent_size = 4

; applies only to Makefiles
[Makefile]
indent_style = tab

; applies only to JSON files
[*.json]
indent_size = 2

; applies only to Markdown files
[*.md]
trim_trailing_whitespace = false

You can see in the above sample, that one file can be used for multiple, if all files you’ll have in your source code. The above has global settings, in the first element, then has settings for PHP, Makefile, JSON, and Markdown files.

The documentation outlines a simplified regular expression syntax, which you can see below, one you may be familiar with if you edit .gitignore files by hand.

I hope that, if you’re serious about applying a consistent format across code in your organization, by all your developers, that you’ll strongly consider using EditorConfig. It’s free, in a standard file format, and nearly ubiquitously available, in all the modern IDEs and editors.