EditorConfig и польза его применения для стандартизации стилей кода

Перевод статьи «Why You Should Use EditorConfig to Standardize Code Styles».

Вы используете EditorConfig для определения соглашений по форматированию файлов в проекте? Прекрасно! Он имеет широкую поддержку, не привязан ни к какому языку программирования, фреймворку или редактору.

EditorConfig, по сути, — просто конфигурационный файл. Для реализации поддержки объявленных в нем правил применяются сторонние инструменты или интеграции.

Файлы EditorConfig читаются IDE (интегрированными средами разработки), редакторами кода и инструментами сборки, которые и обеспечивают применение нужных стилей.

Какие проблемы решает EditorConfig?

Обычно разработчики настраивают стили кода в редакторе в соответствии с собственными предпочтениями. К сожалению, их предпочтения могут не совпадать с вашими.

Что происходит, когда много разных людей с разными предпочтениями являются контрибьюторами одного проекта? Речь может идти о проекте на вашей работе или же open-source проекте на GitLab или GitHub.

К файлам, с которыми работают контрибьюторы, применяются их собственные настройки стилей. В результате проекты могут стать непоследовательными и неряшливыми. В них могут появиться следующие проблемы:

  • смесь табов и пробелов
  • разные символы перевода строки (обычно при использовании Git это не является существенной проблемой)
  • файлы могут не иметь желаемой кодировки символов
  • в разных файлах могут быть разные размеры отступов

Когда код непоследователен, он кажется неопрятным и его тяжело читать (это еще зависит от среды разработки).

eclipse.jdt.ls со смешанными табами и пробелами. Вид в GitHub с tab size = 8

Распространенное решение этих проблем — общие настройки редактора как часть проекта. Но это предполагает, что все участники будут использовать одинаковые редакторы, а такое маловероятно.

Только для разработки на Java у нас на выбор несколько вариантов редакторов и IDE:

Если добавлять файлы конфигурации для всех редакторов, которые кто-то может использовать, это лишь напрасно раздует проект.

Как насчет универсального решения, при котором ответственность за использование общей конфигурации лежит на самом редакторе?

Чем полезен EditorConfig

Общие соглашения относительно стиля кода играют большую роль в проекте. Они помогают существенно экономить время благодаря следующим аспектам их использования.

EditorConfig делает код более читаемым

Улучшение читабельности кода — самая важная причина использовать общие настройки стилей. Это помогает поддерживать проект и позволяет работать быстрее.

«На чтение кода мы тратим в 10 раз больше времени, чем на его написание. Мы постоянно читаем старый код — это часть работы по написанию нового. Таким образом, облегчая чтение кода, мы облегчаем и его написание», — Роберт Мартин.

Но ваш код могут читать не только разработчики, создающие проект. Это могут быть:

  • исследователи, которым нужно более детально разобраться в работе проекта
  • аналитики безопасности, проверяющие проект на уязвимости
  • технические писатели, документирующие поведение программы.

Если ваш код будет чистым, последовательным и человекочитаемым, все эти люди смогут более эффективно выполнять свою работу.

EditorConfig облегчает код-ревью

Если вы — мейнтейнер проекта, вы неизбежно столкнетесь с необходимостью проверять чужой код. Это может быть код ваших товарищей по команде или open-source контрибьюторов, обнаруживших ваш проект и захотевших принять участие.

Принудительное применение нужного форматирования стоит доверить программному обеспечению. Благодаря этому чтение и проверка кода станут более эффективными, а запрашивать изменения, связанные с форматированием, вообще не придется.

Ускорение цикла обратной связи очень сильно экономит время всем участникам процесса.

EditorConfig облегчает разработку

Наличие соглашений о стиле кода и автоматическое применение правил редактором избавляет разработчиков от лишней головной боли.

Без всего этого им пришлось бы самостоятельно разыскивать руководство по стилю и руководство для контрибьюторов, а потом вручную проверять код на соответствие соглашениям.

И даже если правила соглашений всем известны, они могут конфликтовать с настройками редактора у разработчика. В таком случае ему придется писать код, не соответствующий автоматическому форматированию в редакторе, либо менять настройки редактора.

Это имеет особое значение для программистов, часто меняющих проекты. Например, open-source контрибьюторы часто пишут код для проектов разных организаций, в которых придерживаются разных соглашений.

Как работает EditorConfig

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

Например, в своем редакторе я использую для XML-файлов отступы в два пробела, но в проекте, где я выступаю контрибьютором, применяются 4-пробельные отступы.

Раздел файла .editorconfig, указывающий, что XML-файлы должны иметь отступы в 4 пробела:

[*.xml]
indent_size = 4

Когда я открываю проект, мой редактор видит файл .editorconfig и перезаписывает настройки, чтобы они соответствовали соглашениям проекта.

Написание XML-файла с моими дефолтными настройками редактора. Я использую отступы в 2 пробела.
Автоматическое переформатирование файла после перезаписи настроек, касающихся XML-файлов.

Как использовать EditorConfig

Возможно, ваш редактор уже поддерживает EditorConfig. Проверить, входит ли он в список редакторов с нативной поддержкой EditorConfig, можно на странице «No Plugin Necessary». IDE от JetBrains и Visual Studio в списке есть.

Если ваш редактор не имеет нативной поддержки, вы скорее всего сможете добавить ее при помощи плагина. Такие редакторы, как Visual Studio Code и Eclipse, поддерживают использование EditorConfig именно таки м образом. Плагины можно найти на сайте EditorConfig — «Download a Plugin».

После установки редактор должен автоматически находить файл .editorconfig в проекте (если он там есть, конечно) и применять правила из этого файла.

Как определять правила в EditorConfig

Список правил можно найти на Вики-странице EditorConfig. Там есть все официально поддерживаемые правила, а также предложения правил, относящихся к определенным доменам. Эти последние могут поддерживаться некоторыми реализациями.

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

В файле EditorConfig верхнего уровня (обычно верхнеуровневый конфиг будет в корне вашего проекта) нужно установить root = true.

Во вложенных директориях могут быть свои файлы EditorConfig, но для них root = true не устанавливается.

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

# Declares that this is the top-level configuration
root = true

# Applies to all files
[*]
indent_style = space
indent_size = 2

# Applies to all Markdown files
[*.md]
trim_trailing_whitespace = false

# Applies to all C# and Java files, overriding rules declared before
[*.{cs,java}]
indent_size = 4

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

Определение правил для каждого отдельного проекта

Просто добавляйте .editorconfig, когда он вам нужен. Например, можно определять правила или добавлять форматы файлов по мере роста проекта.

Начальный файл .editorconfig может быть сгенерирован вашим редактором или создан вручную. Содержимое можно скопировать в примере на официальном сайте.

Определение правил для всех проектов

Или же вы можете собрать все свои предпочтения воедино и спланировать идеальную конфигурацию для всех файлов, с которыми вам может случиться работать.

Начать можно с нуля, а можно скопировать мой вариант и внести нужные изменения.

Файл .editorconfig, который я использую во всех проектах, которые поддерживаю:

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
curly_bracket_next_line = false
spaces_around_operators = true

[*.bat]
end_of_line = crlf

[*.cs]
curly_bracket_next_line = true

[*.{cpp,cs,gradle,java,kt,py,rs}]
indent_size = 4

[*.{js,ts}]
quote_type = single

[*.md]
trim_trailing_whitespace = false

[*.tsv]
indent_style = tab

Рекомендации по правилам EditorConfig

Я советую объявить эти правила, если в вашем проекте есть файлы соответствующих форматов. Это поможет избежать больших проблем, связанных с пользовательскими настройками среди разработки.

Пакетные файлы (batch-файлы)

Переводы строк при сохранении должны иметь текстовые представления. Обычно вы этого не видите и об этом не думаете.

Но в разных системах переводы строк обозначаются по-разному (узнать больше).

  • В Unix-системах используется lf или \n.
  • В Windows — crlf или \r\n.

Batch-файлы, содержащие юниксовские символы перевода строки, ведут себя неожиданным образом. Избежать этого можно, установив end_of_line = crlf. Таким образом обеспечивается применение символов перевода строки Windows. Узнать больше можно здесь.

[*.bat]
end_of_line = crlf

Markdown

В Markdown можно сделать разрыв строки в текущем абзаце путем добавления двух пробелов в конце строки. Но редактор может удалить «лишние» пробелы при сохранении. Чтобы этого избежать, можно для .md-файлов установить trim_trailing_whitespace = false.

[*.md]
trim_trailing_whitespace = false

TSV

TSV-файлы (TSV — значения, разделенные табуляцией) очень напоминают CSV-файлы (CSV — значения, разделенные запятыми). Но, как следует из самого названия, в качестве разделителя в них используются табы.

Разработчики зачастую автоматически конвертируют табы в пробелы. Но если разделители в TSV-файлах заменятся пробелами, ваша таблица превратится в один столбец. Чтобы этого не случилось, установите для .tsv-файлов indent_style = tab.

[*.tsv]
indent_style = tab

Заключение

Если вы — мейнтейнер, я настоятельно советую вам добавить в корень вашего проекта файл .editorconfig, где будут определены соглашения по этому проекту.

Благодаря этому мейнтейнеры смогут просматривать пул-реквесты, соответствующие установленным стилевым правилам, а редактор кода (IDE) будет автоматически применять эти правила.

Людям, работающим над проектом, тоже будет проще. Благодаря перезаписи настроек разработчики смогут писать код так, как удобно им самим, и не заморачиваться с ручной заменой настроек для каждого проекта.

Ваши проекты станут чище, поскольку все правила будут прописаны в одном «независимом» файле, а не в файлах разных редакторов кода.

[customscript]techrocks_custom_after_post_html[/customscript]

[customscript]techrocks_custom_script[/customscript]

Прокрутить вверх