Feature: Add EditorConfig #21092

Motivation

Developers are supposed to follow Coding style. However, from time to time a PR is created and then its author is asked to change tabs to spaces, for example.

Introducing an .editorconfig file can mitigate these formatting issues:

User story

A contributor wants to create a new PR. She clones Bitcoin Core repo, opens her editor, the editor loads .editorconfig rules and writes her patch with correct formatting rules. Less Coding Style issues is then discovered in the PR review process and thus less CI runs are needed.

What is EditorConfig file?

https://editorconfig.org provides very well and concise explanation:

What is EditorConfig?

EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various 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.

Support

.editorconfig is supported in many IDEs and text editors. Sometimes, the support is out-of-box and sometimes a plugin is needed. However, for example, VS Code detects .editorconfig presence and automatically offers you to install the missing plugin.

See https://editorconfig.org/#pre-installed for details on support. Visual Studio is supported, VS Code and IntelliJ IDEA are supported and many others.

My editor does not support .editorconfig

Then nothing really changes for you.

.editorconfig vs .clang-format

As explained here:

Note that Visual Studio also supports EditorConfig, which works in a similar way. ClangFormat, however, has a much larger variety of style options than EditorConfig, including some very C++ specific rules that can be set, and it is already used by C++ developers today.

Having both .editorconfig and .clang-format in a project, may not always work correctly though, I think. As some editors may have a plugin for .editorconfig and a plugin for clang-formatter which may not work correctly in unison.

Proposed .editorconfig

This proposal is based on Developer Notes:

# This is the top-most EditorConfig file.
root = true

# For all files.
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = false

# Shell scripts
[*.sh]
indent_size = 4
indent_style = space
trim_trailing_whitespace = true

# C++ files
[*.{h,cpp}]
indent_size = 4
indent_style = space
trim_trailing_whitespace = true

# Python files
[*.py]
indent_size = 4
indent_style = space
trim_trailing_whitespace = true

# Makefiles
[Makefile,*.am]
indent_style = tab
trim_trailing_whitespace = true

# Markdown files
[*.md]
trim_trailing_whitespace = true

# .cirrus.yml, .appveyor.yml, .fuzzbuzz.yml, etc.
[*.yml]
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

Note that the syntax can be much shorter but it is not my goal here, I prefer clarity at this point.

So what is this specifying:

• charset: Use UTF-8 in all files.
• end_of_line: Line endings should be LF by default in all files.
• insert_final_newline: Do not add a blank line at the end of a file by default.

And then there are rules for various types of files.

The rules does not cover everything. One can see that there actually many different file types (meaning, unique file extensions) using this simple PowerShell script:

Get-ChildItem -Recurse | % {$_.Extension.ToLower()} | sort | unique

with the following output:

.1
.ac
.adoc
.am
.bash-completion
.bat
.bmp
.c
.cc
.cert
.cfg
.clang_complete
.clang-format
.cmake
.cmd
.cnf
.com
.conf
.cpp
.css
.csv
.doxyfile
.dtd
.empty
.exe
.exp
.gci
.gitattributes
.github
.gitignore
.gitmodules
.guess
.h
.hex
.hpp
.html
.icns
.ico
.idb
.ilk
.in
.include
.ini
.init
.ipp
.jam
.js
.json
.lastbuildstate
.lib
.list
.log
.m
.m4
.md
.mk
.mm
.moc
.obj
.openrc
.openrcconf
.patch
.pc
.pdb
.pl
.plist
.png
.po
.pro
.py
.python-version
.qbk
.qm
.qml
.qrc
.raw
.rb
.rc
.recipe
.res
.s
.sage
.sass
.scm
.scss
.service
.sgml
.sh
.sln
.spec
.sub
.supp
.svg
.targets
.td
.tlog
.ts
.tx
.txt
.ui
.user
.v2
.vcxproj
.verbatim
.vscode
.xml
.xpm
.xsl
.y
.yapf
.yml
.yy

What do you think?

Concept ACK, I think the editorconfig idea is quite elegant.

I like that it works on a lower level than clang-format, it specifies basic formatting such as character set, indentation and newline use. So it also works for editors that don't have language specific parsing. There seem to be plugins for a lot of editors that don't have built-in support.

Concept ACK

I think we should be very liberal with accepting editor dotfiles for obvious reasons:

They help people using an editor which understands the dotfile in question, and everyone else can safely ignore them.

We're not in the business of dictating what tools people should use: that's nanny state behaviour :)

Concept ACK Never heard of the EditorConfig project before but seems to be a very nice solution for a common problem. Although this is already one step further, but also specifying a soft limit for line lengths would be nice (soft in the sense that it is not enforced by the editor, but only visually shown e.g. as a colored column), if this ends up in the coding guidelines (as proposed in #20986).