Определение согласованных стилей программирования с помощью EditorConfig

Чтобы обеспечить согласованные стили программирования для всех, кто работает в базе кода, можно добавить файл .editorconfig в решение или проект. Параметры файла EditorConfig соответствуют спецификации формата файла, поддерживаемой EditorConfig.org. Многие редакторы кода и приложения поддерживают файлы EditorConfig, включая Visual Studio. Вы можете использовать несколько .editorconfig файлов, и их можно включить в состав базы кода.

Вы можете вручную заполнить файл EditorConfig или автоматически создать его на основе параметров стиля кода, выбранных в Visual Studio. Дополнительные сведения см. в разделе "Добавление и удаление файлов EditorConfig".

При добавлении файла EditorConfig в проект в Visual Studio только новые строки кода форматируются на основе параметров EditorConfig. Форматирование существующего кода не изменяется, если только вы не запускаете команды очистки кода или форматирования документа . Дополнительные сведения см. в разделе "Применение стилей кода".

Для .NET Visual Studio отображает форматированную версию .editorconfig файла вместо обычного текстового файла.

EditorConfig и предпочтения стиля кода

В Visual Studio параметры файла EditorConfig приоритетны по сравнению с параметрами глобального текстового редактора, доступными в разделе Инструменты>Параметры>Текстовый редактор>[C# | C/C++ | Visual Basic]>Стиль кода. Файл EditorConfig можно использовать для настройки каждой базы кода для использования параметров текстового редактора, относящихся к проекту.

При использовании файла EditorConfig можно по-прежнему задавать собственные параметры редактора в текстовом редакторе Visual Studio. Эти параметры текстового редактора применяются всякий раз, когда вы работаете в базе кода без файла EditorConfig или когда файл EditorConfig не переопределяет определенный параметр. Пример такого предпочтения заключается в том, следует ли использовать вкладки или пробелы для стиля отступа кода.

Согласованность кода

Параметры файла EditorConfig позволяют поддерживать согласованные стили кода и соглашения в базе кода независимо от используемого редактора или интегрированной среды разработки. Некоторые стили кода, которые вы можете настроить, включают задание стиля отступов, ширину табуляции, символы конца строки и кодировку. Например, если в кодовой базе на C# принято делать отступы из пяти пробелов, использовать кодировку UTF-8 в документах, а строки заканчивать на CR/LF, можно настроить файл EditorConfig для соблюдения этого соглашения. Сведения о поддерживаемых соглашениях см. в разделе "Поддерживаемые параметры".

Файлы EditorConfig полезны, когда соглашения о кодировке, которые вы используете в своих личных проектах, отличаются от соглашений, используемых в проектах вашей команды. Например, вы можете предпочесть, чтобы отступ добавлял символ табуляции в ваш код. Однако ваша команда может предпочесть, чтобы отступ составлял четыре пробела. Файлы EditorConfig устраняют эту проблему, позволяя иметь конфигурацию для каждого сценария.

Так как файл .editorconfig в базе кода содержит параметры EditorConfig, они перемещаются вместе с этой базой кода. Если вы открываете файл кода в редакторе, совместимом с EditorConfig, параметры текстового редактора активируются.

Поддерживаемые параметры

EditorConfig поддерживает все поддерживаемые Visual Studio языки, кроме XML.

Для каждого языка редактор в Visual Studio поддерживает основной набор свойств EditorConfig:

• indent_style
• размер отступа
• Ширина вкладки
• конец_строки
• кодировка
• удалить_пробелы_в_конце_строки
• командная вставка_окончательной_новой_строки
• корень

Для C# и Visual Basic EditorConfig также поддерживает правила стиля кода , включая язык, форматирование и именование. Например, можно указать правило языка C# относительно использования var при определении переменных. Кроме того, можно указать правило именования, которое имена асинхронных методов должны содержать суффикс Async.

Добавление и удаление файлов EditorConfig

При добавлении файла EditorConfig в проект или базу кода Visual Studio форматирует все новые строки кода, которые вы записываете в соответствии с параметрами файла EditorConfig. Однако Visual Studio не преобразует существующие стили в новые, пока не отформатируйте документ или не выполните очистку кода. Например, если отступы в вашем файле отформатированы с помощью табуляций, и вы добавляете файл EditorConfig, который форматирует отступы пробелами, символы отступов не преобразуются в пробелы автоматически. При форматировании документа (выберите Изменить>Дополнительные>Форматировать документ или нажмите Ctrl+K, Ctrl+D), настройки пробелов из файла EditorConfig применяются к существующим строкам кода.

При удалении файла EditorConfig из проекта или базы кода необходимо закрыть и повторно открыть все открытые файлы кода для параметров глобального редактора, чтобы повлиять на новые строки кода.

Visual Studio автоматически использует файлы EditorConfig, присутствующих в базе кода, на основе иерархии папок.

Если файл EditorConfig отсутствует, его можно добавить в проект с помощью одного из следующих методов:

• создавайте автоматически файл EditorConfig на основе параметров стиля кода.

• Вручную добавьте файл EditorConfig.

• Используйте IntelliCode для Visual Studio для создания файла .editorconfig в решении. Щелкните правой кнопкой мыши в Solution Explorer и в контекстном меню выберите Добавить>новый EditorConfig (IntelliCode). IntelliCode для Visual Studio определяет стили кода из существующего кода, а затем создает файл EditorConfig с предопределенными параметрами стиля кода.

Создание EditorConfig из параметров стиля кода

Добавление файла EditorConfig в проект

Чтобы добавить файл EditorConfig в проект или решение, выполните следующие действия.

1. Откройте проект или решение в Visual Studio. Выберите решение или узел проекта в зависимости от того, должны ли параметры EditorConfig применяться ко всем проектам в решении или только к одному. Вы также можете выбрать папку в проекте или решении, чтобы добавить в нее файл .editorconfig.

2. В меню выберите Project>Добавить новый элементили нажмите клавиши CTRL+SHIFT+A.

   Диалоговое окно добавления нового элемента открывается.

3. В поле поиска введите editorconfig.

   В результатах поиска отображаются два шаблона элементов editorconfig File.

   

   Если шаблон элемента не отображается, необходимо добавить файл вручную или добавить версию Intellicode .editorconfig, а затем изменить ее на ваш язык.

4. Выберите шаблон editorconfig File (empty), чтобы добавить файл EditorConfig, предварительно заполненный параметрами EditorConfig по умолчанию для пробелов, стиля кода и соглашений об именовании. Или выберите шаблон EditorConfig (.NET), чтобы добавить файл EditorConfig, предварительно заполненный стандартными настройками по умолчанию для .NET, включая пробелы, стиль кода и соглашения об именовании.

   Новый файл .editorconfig отображается в обозревателе решений и открывается в редакторе в качестве новой вкладки.

   Для .NET Visual Studio предоставляет форматированную версию файла, как показано ниже.

   

5. При необходимости измените файл и сохраните его.

Иерархия файлов и приоритет

При добавлении файла .editorconfig в папку в иерархии файлов его параметры применяются ко всем применимым файлам на этом уровне и ниже. Вы также можете переопределить параметры EditorConfig для определенного проекта, базы кода или части базы кода, чтобы использовать разные соглашения, отличные от других частей базы кода. Это может быть полезно при включении кода из другого места, если вы не хотите изменять его соглашения.

Следуйте этим рекомендациям:

• Чтобы переопределить некоторые или все параметры EditorConfig, добавьте файл .editorconfig на том уровне иерархии файлов, к которому вы хотите применить изменённые параметры. Новые параметры файла EditorConfig применяются к файлам на том же уровне и файлах в любых подкаталогах.

  

• Если вы хотите переопределить некоторые параметры, но не все параметры, укажите только эти параметры в файле .editorconfig. Переопределяются только те свойства, которые вы явно перечисляете в .editorconfig файле более низкого уровня. Другие параметры из любых файлов с более высоким уровнем .editorconfig продолжают применяться.

• Если вы хотите убедиться, что к этой части базы кода не применяются параметры из файлов с более высоким уровнем .editorconfig, добавьте свойство root=true в файл .editorconfig нижнего уровня.

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

Файлы EditorConfig считываются сверху вниз. Если есть несколько свойств с одинаковым именем, последнее найденное свойство с одинаковым именем имеет приоритет.

Изменение файлов EditorConfig

Пример

В следующем примере показано состояние отступа фрагмента кода C# до и после добавления файла EditorConfig в проект:

1. В диалоговом окне ">Опции", настройте параметры редактора текста Visual Studio для C#, чтобы вкладки создавали четыре пробела при нажатии клавиши Tab.

   

2. Как и ожидалось, при нажатии клавиши Tab на следующей строке она делает отступ, добавляя четыре пробела.

   

3. Используйте EditorConfig для переключения параметров вкладок для использования вкладок.

   Выберите Использовать вкладки в файле EditorConfig.

   

4. При нажатии клавиши вкладки теперь вместо пробелов отображаются символы вкладок.

   

Устранение неполадок параметров EditorConfig

Если файл EditorConfig существует в любом месте структуры каталогов в расположении проекта или выше, Visual Studio применяет параметры редактора в этом файле к редактору. В этом случае в строке состояния может появиться следующее сообщение:

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

Это означает, что если какие-либо настройки редактора в Сервисе>Параметры>Текстовый редактор (например, размер и стиль отступа, размер табуляции или соглашения о кодировании) указаны в файле EditorConfig на уровне проекта или выше в структуре каталогов, то соглашения в файле EditorConfig переопределяют параметры в Текстовом редакторе.

Чтобы устранить неполадки EditorConfig, выполните следующие действия.

1. Чтобы отключить поддержку EditorConfig для Visual Studio, снимите флажок Следовать соглашениям о кодировании проекта в Tools>Options>Text Editor.

   

2. Чтобы найти файлы EditorConfig в родительских каталогах проекта, откройте командную строку и выполните следующую команду из корня диска, содержащего проект.

   dir .editorconfig /s
   

3. Чтобы управлять областью соглашений EditorConfig, задайте свойство root=true в файле .editorconfig в корне репозитория или в каталоге, который находится в проекте.

   Visual Studio ищет файл с именем .editorconfig в каталоге открытого файла и в каждом родительском каталоге. Поиск заканчивается, когда он достигает корневого пути к файлу или если найден файл .editorconfig с root=true.

Связанное содержимое

• опции правила оформления кода для .NET
• Поддержка EditorConfig для языковой службы
• EditorConfig.org
• функции редактора кода
• файлы конфигурации для правил анализа кода