Definindo regras de formatação no .NET com EditorConfig

Introduction

Quando trabalhamos com outras pessoas, usando editores e IDEs variadas, é comum que haja diferenças nas configurações dos mesmo, fazendo com que se perca consistência no estilo de formatação do código. Por exemplo:

Usando tabs/espaços e tamanhos de indentação diferentes, dificultando a leitura do código;
Usando encodings diferentes entre os arquivos, causando erros difíceis de serem encontrados (mostrando caracteres inválidos) e quebrando testes automatizados.

Nesse post eu vou mostrar como manter um padrão para todos que trabalham no código, independente do editor utilizado, e em um próximo post eu mostrarei como validar essas (e outras) regras em tempo de compilação e na esteira de integração contínua.

Introduzindo o arquivo EditorConfig

O arquivo EditorConfig é usado por editores e IDEs para definir preferências de formatação do projeto. Sem ele, as IDEs e editores irão usar suas configurações padrões, causando divergências entre arquivos editados neles.

Muitos editores e IDEs suportam o arquivo EditorConfig por padrão, e outros suportam através de plugins. Alguns exemplos:

Visual Studio (Por padrão);
JetBrains Rider (Por padrão);
GitHub (Por padrão);
VS Code (Plugin);
Vim (Plugin);
Emacs (Plugin);
Sublime (Plugin);

O arquivo tem o nome .editorconfig e é um arquivo INI onde as seções são filtros por nome dos arquivos, por exemplo:

[*.cs] para regras aplicadas a arquivos .cs;
[scripts/**.js] para regras aplicadas a arquivos javascript dentro de uma pasta scripts e seus subdiretórios;
[{package.json}] para regras aplicadas apenas ao arquivo package.json.

Mais detalhes aqui

O arquivo EditorConfig pode ser colocado em qualquer diretório do projeto e sobrescrito por outro EditorConfig em diretórios filhos, mas para ficar mais claro, costumo deixá-lo na mesma pasta do arquivo da solution do .NET (.sln).

Adicionando um EditorConfig ao seu projeto

Para incluir um EditorConfig ao seu projeto, basta criar um arquivo com o nome .editorconfig no mesmo diretório da sua solution (arquivo .sln) com o conteúdo abaixo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# EditorConfig principal.
root = true

# Seções para arquivos C#
# As regras abaixo serão aplicadas apenas aos arquivos .cs
[*.cs]

# Indentação e espaçamento
indent_style = space
indent_size = 4

# Preferências de novas linhas
end_of_line = crlf
insert_final_newline = false
trim_trailing_whitespace = true

# Preferências de encoding
charset = utf-8

O arquivo define as seguintes regras:

root: Arquivos editorconfig em diretórios superiores não serão lidos;
indent_style: A indentação deve utilizar espaço;
indent_size: A indentação deve usar 4 caracteres de espaço;
end_of_line: Linhas devem terminar com os caracteres CR+LF;
insert_final_newline: Não inserir automaticamente linhas em branco no final dos arquivos;
trim_trailing_whitespace: Linhas vazias não devem ter caracteres em branco;
charset: Os arquivos devem ser salvos usando o formato UTF-8.

Mais detalhes aqui.

⚠️ O GIT permite alterar o final da linha para LF ao fazer pushes para o repositório e alterar de volta para CRLF nos checkouts. Então, a configuração end_of_line pode ser configurada como CRLF sem problemas. O GIT for Windows sugere essa configuração como padrão durante a instalação. Detalhes de como configurar aqui.
⚠️ UTF-8 with BOM não é requerido e nem recomendado, de acordo com o padrão Unicode. Detalhes aqui.
ℹ️ Em .NET, o arquivo EditorConfig também pode ser usado para definir regras e severidades para os analyzers específicos para a plataforma .NET. Em um próximo post, vou mostrar como configurar essas regras.

Aplicando as novas regras de formatação ao código

Quando nós alteramos as regras de formatação de um projeto existente, as alterações não são aplicadas automaticamente. Precisamos executar manualmente a função de formatação automática da IDE.

Visual Studio

Primeiro, nós precisamos incluir o fixer Format document no perfil do Code Cleanup.

1 - Acesse Analyze > Code Cleanup > Configure Code Cleanup.

2 - Inclua o fixer Format document no perfil que deseja executar ao salvar.

Incluindo o fixer Format document no perfil do Code Cleanup

3 - No menu, selecione Analyze > Code Cleanup > Run Code Cleanup (Yout Profile) on Solution.

⚠️ A função de formatação do Visual Studio não altera o encoding do arquivo. Para isso é necessário utilizar o dotnet-format ou outra ferramenta.

VS Code

O VS Code não possui a funcionalidade de formatar todos os arquivos ao mesmo tempo. Para isso é necessário utilizar a extensão Format Files.

1 - Instale a extensão Format Files.

2 - Acesse View > Command Palette ou pressione Ctrl+Shift+P.

3 - Selecione a opção Start Format Files: Workspace ou a opção Start Format Files: From Glob.

JetBrains Rider

Acesse Code > Reformat Code ou pressione Ctrl+Alt+Enter.

Format on save

Quando criamos um arquivo EditorConfig, as IDEs irão usar as configurações dele para suas funcionalidades de formatação automática.

Aqui eu mostro como habilitar a formatação automática ao salvar os arquivos em algumas IDEs.

Formatar ao salvar no Visual Studio

O Visual Studio 2022 não tem a funcionalidade de formatar ao salvar, porém, ele permite executar um perfil do Code Cleanup ao salvar. Dessa forma, podemos configurar um perfil do Code Cleanup para executar o fixer Format document e executar esse perfil ao salvar.

ℹ️ Para o Visual Studio 2019, existe uma extenção que habilita a mesma funcionalidade.

1 - Configure seu perfil do Code Cleanup para executar o fixer Format document, como mostrado na seção anterior deste post.

2 - Acesse Tools > Options > Text Editor > Code Cleanup.

3 - Marque a opção Run Code Cleanup profile on Save e selecione o perfil do Code Cleanup para executar ao salvar.

Run Code Cleanup profile on Save

Agora o Visual Studio irá formatar seus arquivos toda vez que você salvá-los.

Formatando ao salvar

Formatar ao salvar no VS Code

1 - Acesse File > Preferences > Settings.

2 - Acesse Text Editor > Formatting ou pesquise por editor.formatOnSave.

Format on save

3 - Marque a opção Editor: Format On Save.

Formatar ao salvar no JetBrains Rider

1 - Acesse File > Settings > Tools > Actions on Save.

2 - Marque a opção Reformat and Cleanup Code.

3 - Selecione o perfil Reformat Code.

Reformat and Cleanup Code on save