Definir estilos de codificação consistentes com EditorConfig

Para impor estilos de codificação consistentes para todos que trabalham em uma base de código, você pode adicionar um arquivo .editorConfig à sua solução ou projeto. As configurações do arquivo EditorConfig seguem uma especificação de formato de arquivo mantida pela EditorConfig.org. Muitos editores de código e aplicativos oferecem suporte a arquivos EditorConfig, incluindo o Visual Studio. Como as configurações estão em um arquivo, elas acompanham seu código e podem ser usadas até mesmo fora do Visual Studio.

No Visual Studio, as configurações de arquivo EditorConfig têm precedência sobre as várias configurações globais do editor de texto disponíveis em Ferramentas>Opções>Editor de texto>C/C++>Estilo de código. Você pode usar um arquivo EditorConfig para personalizar cada base de código e usar configurações do editor de texto específicas para aquele projeto.

Você pode preencher manualmente um arquivo EditorConfig ou gerá-lo automaticamente com base nas configurações de estilo de código escolhidas no Visual Studio. Para criar um novo arquivo .editorconfig com base nas configurações atuais do Visual Studio, no menu principal do Visual Studio, escolha Ferramentas>Opções>Editor de texto>C/C++>Geral. Em seguida, escolha Gerar arquivo .editorconfig nas configurações. Escolha a pasta onde está o projeto e Selecionar pasta para salvar o arquivo .editorconfig.

Ao usar um arquivo EditorConfig, você ainda pode continuar a definir suas próprias preferências de editor pessoal no editor de texto do Visual Studio. Essas configurações do editor de texto se aplicam sempre que você trabalha em uma base de código sem um arquivo EditorConfig ou quando o arquivo EditorConfig não substitui uma configuração específica. Um exemplo dessa preferência é usar guias ou espaços para o estilo de recuo de código.

Quando você adiciona um arquivo EditorConfig ao projeto no Visual Studio, somente novas linhas de código são formatadas com base nas configurações de EditorConfig. A formatação do código existente não será alterada a menos que você execute um dos seguintes comandos:

• Limpeza de código.

  Selecione Limpeza de código no editor do Visual Studio, ou pressione Ctrl+K, Ctrl+E. Esse comando aplica-se a configurações de espaço em branco, como estilo de recuo, e configurações de estilo de código selecionadas, como preferências de parênteses.

• Formatar Documento.

  Selecione Edit>Avançado>Formatar Documento, ou pressione Ctrl+K, Ctrl+D no perfil padrão. Esse comando aplica-se somente a configurações de espaço em branco, como estilo de recuo.

Consistência do código

As configurações do arquivo EditorConfig permitem que você mantenha estilos e convenções de codificação consistentes em uma base de código, independentemente do editor ou IDE usado. Alguns estilos de codificação que você pode controlar são estilo de recuo, largura de tabulação, caracteres de fim de linha e codificação. Por exemplo, se sua base de código C# tiver uma convenção que recua usando cinco caracteres de espaço, os documentos usam codificação UTF-8 e as linhas terminam com CR/LF, você pode configurar um arquivo EditorConfig para usar essa convenção.

Os arquivos EditorConfig são úteis quando as convenções de codificação que você usa em seus projetos pessoais diferem daquelas convenções usadas nos projetos de sua equipe. Por exemplo, talvez você prefira que um recuo adicione um caractere de tabulação no seu código. Porém, sua equipe pode preferir que um recuo adicione quatro espaços. Arquivos EditorConfig resolvem esse problema permitindo que você tenha uma configuração para cada cenário.

Como um arquivo .editorconfig na base de código contém as configurações de EditorConfig, elas viajam juntamente com essa base de código. Desde que você abra o arquivo de código em um editor em conformidade com EditorConfig, as configurações do editor de texto são ativadas.

Configurações com suporte

O editor no Visual Studio é compatível com o conjunto principal de propriedades do EditorConfig:

• indent_style
• indent_size
• tab_width
• end_of_line
• charset
• trim_trailing_whitespace
• insert_final_newline
• root

O EditorConfig é compatível com todas as linguagens com suporte do Visual Studio, exceto configurações do editor EditorConfig com suporte para XML.

O EditorConfig dá suporte a convenções de estilo de código, incluindo linguagem, formatação e convenções de nomenclatura para C# e Visual Basic.

Adicionar e remover arquivos EditorConfig

Quando você adiciona um arquivo EditorConfig ao seu projeto ou base de código, o Visual Studio formata qualquer linha de código nova que você escreve de acordo com o arquivo EditorConfig. No entanto, o Visual Studio não converte estilos existentes em novos até que você formate o documento ou execute uma Limpeza de Código. Por exemplo, se os recuos no arquivo formatados com tabulações e adicionar um arquivo EditorConfig com recuos com espaços, os caracteres de recuo não serão convertidos automaticamente em espaços. Quando você formata o documento (selecione Editar>Avançado>Formatar Documento ou pressione Ctrl+K, Ctrl+D), as configurações de espaço em branco no arquivo EditorConfig são aplicadas às linhas de código existentes.

Se você remover um arquivo EditorConfig do seu projeto ou da base de código, será necessário fechar e reabrir os arquivos de código aberto para as configurações globais do editor entrarem em vigor nas novas linhas de código.

Adicionar um arquivo EditorConfig a um projeto

Para adicionar um arquivo EditorConfig ao seu projeto ou solução, execute estas etapas:

1. Abra um projeto ou uma solução no Visual Studio. Selecione o nó da solução ou do projeto, dependendo se as configurações de EditorConfig devem ser aplicadas a todos os projetos na solução ou a apenas um. Também é possível selecionar uma pasta no projeto ou na solução para adicionar o arquivo .editorconfig.

2. No menu, selecione Projeto>Adicionar Novo Item, ou pressione Ctrl+Shift+A.

   A caixa de diálogo Adicionar Novo Item é aberta.

3. Na caixa de pesquisa, digite editorconfig.

   Dois modelos de item de Arquivo editorconfig são mostrados nos resultados da pesquisa.

   

4. Selecione o modelo Arquivo editorconfig (vazio) para adicionar um arquivo EditorConfig pré-preenchido com opções padrão do EditorConfig para espaço em branco, estilo de código e convenções de nomenclatura. Ou selecione o modelo Arquivo editorconfig (.NET) para adicionar um arquivo EditorConfig pré-preenchido com convenções de nomenclatura, espaço em branco .NET e estilo de código .NET.

   Um novo arquivo .editorconfig aparece no Gerenciador de Soluções e é aberto no editor como uma nova guia.

   

5. Opcionalmente, edite o arquivo e salve-o.

Outras formas de adicionar um arquivo EditorConfig

Há algumas outras maneiras de adicionar um arquivo EditorConfig ao projeto:

• Use o IntelliCode para Visual Studio para gerar um arquivo .editorconfig na sua solução. Clique com o botão direito do mouse no Gerenciador de Soluções e selecione Adicionar>Novo EditorConfig (IntelliCode) no menu de contexto. O IntelliCode para Visual Studio infere seus estilos de código do código existente e, em seguida, cria um arquivo EditorConfig com suas preferências de estilo de código predefinidas.

• Gere automaticamente um arquivo EditorConfig com base em suas configurações de estilo de código.

Precedência e hierarquia de arquivos

Quando você adiciona um arquivo .editorconfig a uma pasta em sua hierarquia de arquivos, as configurações se aplicam a todos os arquivos aplicáveis nesse nível e abaixo dele. Você também pode substituir as configurações de EditorConfig para um projeto específico, uma base de código ou parte de uma base de código, de modo que ele use convenções diferentes do que as outras partes da base de código. Isso pode ser útil quando você incorpora código de outro lugar e não quer alterar suas convenções.

Siga estas diretrizes:

• Para substituir algumas ou todas as configurações do EditorConfig, adicione um arquivo .editorconfig no nível da hierarquia de arquivos em que você deseja aplicar essas configurações substituídas. As novas configurações de arquivo do EditorConfig aplicam-se aos arquivos no mesmo nível e a arquivos em qualquer subpasta.

  

• Se você quiser substituir algumas, mas não todas as configurações, especifique apenas essas configurações no arquivo .editorconfig. Somente as propriedades que você listar explicitamente no arquivo .editorconfig de nível inferior são substituídas. Outras configurações de quaisquer arquivos .editorconfig de nível superior continuam a ser aplicadas.

• Se você quiser garantir que nenhuma configuração de nenhum arquivo .editorconfig de nível superior seja aplicada a esta parte da base de código, adicione a propriedade root=true ao arquivo .editorconfig de nível inferior.

  # top-most EditorConfig file for this level
  root = true
  

Os arquivos EditorConfig são lidos de cima para baixo. Se houver várias propriedades com o mesmo nome, a propriedade mais recente encontrada com o mesmo nome terá precedência.

Editar os arquivos EditorConfig

Exemplo

O exemplo a seguir mostra o estado de recuo de um snippet de código C# antes e depois de adicionar um arquivo .EditorConfig ao projeto:

1. Na caixa de diálogo Ferramentas>Opções, defina as configurações de Editor de texto>C#>Tabs para o editor de texto do Visual Studio para inserir quatro caracteres de espaço quando você pressionar a tecla Tab.

   

2. Conforme esperado, ao pressionar a tecla Tab na próxima linha, ele recua por meio da adição de quatro caracteres de espaço em branco.

   

   

3. Use EditorConfig para alterar a configuração de guias para usar guias.

   Selecione Usar Tabs no arquivo EditorConfig.

   

   Adicione um novo arquivo chamado .editorconfig ao projeto, com o conteúdo a seguir. O indicador [*.cs] significa que essa alteração se aplica somente a arquivos de código C# no projeto.

   # Top-most EditorConfig file
   root = true
   
   # Tab indentation
   [*.cs]
   indent_style = tab
   

4. Ao pressionar a tecla Tab, agora você obtém caracteres de tabulação em vez de espaços.

   

   

Solução de problemas de configurações do EditorConfig

Se existir um arquivo do EditorConfig na estrutura do diretório no local do seu projeto ou acima desse local, o Visual Studio aplicará as configurações do editor nesse arquivo ao seu editor. Nesse caso, você poderá ver a seguinte mensagem na barra de status:

User preferences for this file type are overridden by this project's coding conventions.

Isso significa que, se as configurações do editor em Ferramentas>Opções>Editor de Texto (como tamanho e estilo do recuo, tamanho da tabulação ou convenções de codificação) forem especificadas em um arquivo EditorConfig no projeto ou acima dele na estrutura de diretório, as convenções no arquivo EditorConfig substituirão as configurações no Editor de texto.

Para solucionar problemas do EditorConfig, siga estas etapas:

1. Para desativar o suporte a EditorConfig para Visual Studio, desmarque a opção Seguir convenções de codificação de projeto em Ferramentas>Opções>Editor de texto.

   

2. Para localizar quaisquer arquivos EditorConfig nos diretórios pai do seu projeto, abra um prompt de comando e execute o seguinte comando na raiz do disco que contém o seu projeto.

   dir .editorconfig /s
   

3. Para controlar o escopo das convenções do EditorConfig, configure a propriedade root=true no arquivo .editorconfig na raiz do seu repositório ou no diretório em que o projeto reside.

   O Visual Studio procurará um arquivo chamado .editorconfig no diretório do arquivo aberto e em todos os diretórios pai. A pesquisa terminará quando atingir o caminho do arquivo raiz ou se um arquivo .editorconfig com root=true for encontrado.

Conteúdo relacionado

• Opções de regra de estilo de código do .NET
• Suporte ao EditorConfig para o serviço de linguagem
• EditorConfig.org
• Recursos do editor de código
• Arquivos de configuração para regras de análise de código