Как настроить правила форматирования кода в проекте: рабочие инструменты

Правила форматирования кода задают единый вид файлов и помогают избегать несогласованных изменений при совместной работе. Чтобы внедрить их безопасно, сначала проверьте текущие настройки проекта, выберите основной форматтер, зафиксируйте конфигурацию в репозитории и проверьте её в редакторе и CI. Меняйте существующий код постепенно, отдельными коммитами.

Опорные решения для единых правил кода

• Проверьте конфигурации, редакторные настройки и историю форматирования до изменений.
• Назначьте один источник правил для каждого типа файлов; избегайте конкурирующих форматтеров.
• Храните общую конфигурацию и версии инструментов в репозитории.
• Сначала применяйте правила к небольшому набору файлов и проверяйте diff.
• Добавляйте проверки в CI поэтапно, не смешивая форматирование с функциональными изменениями.

Сначала выясните, где проект уже расходится по стилю

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

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

1. Найдите файлы конфигурации форматтеров и линтеров, а также настройки редактора.
2. Проверьте, какие команды запускаются локально и в CI.
3. Посмотрите на несколько типичных файлов и историю недавних изменений: выясните, какие отличия вызваны форматированием, а какие - логикой.
4. Составьте перечень языков, генерируемых файлов и каталогов, которые нужно исключить или обрабатывать отдельно.

Выберите форматтер и зафиксируйте единственный источник правил

До выбора инструмента уточните, какие языки используются и какие форматтеры уже поддерживает проект. Например, настройка Prettier подходит для языков и типов файлов, которые он обрабатывает, а настройка ESLint нужна для правил анализа кода; в некоторых проектах часть правил форматирования может пересекаться с линтером.

Подход	Когда уместен	Что проверить
Форматтер как отдельный инструмент	Нужно единообразно приводить поддерживаемые файлы к заданному виду.	Совместимость с языками, конфигурацию и версию в проекте.
Линтер с правилами оформления	Команда уже использует линтер и хочет проверять стиль вместе с другими правилами.	Не дублируют ли его правила отдельный форматтер.
Форматтер и линтер вместе	Нужны и автоматическое форматирование, и проверки качества кода.	Разделение ответственности и отсутствие конфликтующих правил.

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

Настройте конфигурацию под языки и структуру репозитория

Перед изменениями учтите риски: автоматическое форматирование может создать большой diff; конфигурация для одного языка не обязательно подходит другим; исключение важных файлов ослабляет проверку; персональные настройки редактора могут отличаться от командных. Начинайте с чистой рабочей копии и сначала проверяйте результат на ограниченном наборе файлов.

1. Определите область действия. Перечислите расширения и каталоги, которые форматируются. Отдельно отметьте сгенерированные файлы, зависимости и другие пути, которые не следует менять автоматически.
2. Создайте конфигурацию в репозитории. Добавьте файл настроек выбранного инструмента в согласованное место. Задайте только правила, которые команда действительно приняла, и избегайте дублирования настроек в нескольких файлах.
3. Настройте исключения. Укажите, какие файлы и каталоги форматтер должен пропускать. Проверьте, что исключения не скрывают исходный код, который команда собирается проверять.
4. Зафиксируйте версии и команды. Опишите установку инструмента и команды для проверки и применения форматирования в документации или конфигурации проекта. Используйте одинаковый способ запуска локально и в CI.
5. Проверьте пробный запуск. Запустите проверку или форматирование на нескольких репрезентативных файлах, затем изучите diff. Если меняются неожиданные файлы или результат нестабилен, остановитесь и скорректируйте область действия.
6. Согласуйте правила с линтером. Убедитесь, что проверка не требует оформления, противоречащего форматтеру. Если часть правил перенесена в форматтер, отключите дублирующую проверку в линтере там, где это поддерживается.

Свяжите форматирование с редактором и сохранением файлов

Настройка редактора должна использовать конфигурацию проекта, а не заменять её. Проверьте результат по списку:

• Редактор распознаёт нужный форматтер для файлов проекта.
• Командные настройки хранятся в репозитории и доступны всей команде.
• Форматирование при сохранении включено только для согласованных типов файлов.
• Линтер и форматтер не перезаписывают результат друг друга.
• Командная проверка запускается из терминала и даёт понятный результат.
• Проверены файлы с разными расширениями и из разных каталогов.
• После повторного форматирования diff не меняется без причины.
• Документация объясняет, как установить инструменты и запустить проверку.

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

Проверьте правила в CI без блокировки всей команды

Добавляйте автоматическую проверку после того, как локальный запуск и конфигурация согласованы. Частые ошибки при внедрении:

• Запускать CI-проверку до фиксации версии инструмента, из-за чего результаты могут различаться.
• Одновременно менять форматирование и логику в одном большом коммите.
• Включать автоматическое исправление в CI без явного решения команды и проверки изменяемых файлов.
• Проверять весь репозиторий, включая генерируемые или исключённые файлы.
• Оставлять форматтер и линтер с конфликтующими правилами.
• Не объяснять разработчикам, как локально устранить ошибку CI.
• Включать обязательную проверку, не проверив её на существующей ветке и типичных изменениях.
• Игнорировать различия между локальной командой и командой, настроенной в CI.

На первом этапе CI может только сообщать о несоответствиях или проверять выбранную область. Переводите проверку в обязательный статус, когда команда умеет запускать её локально и понимает, как исправлять ошибки.

Внедряйте изменения постепенно, чтобы не затронуть лишний код

Выберите способ внедрения по размеру репозитория, риску массового diff и готовности команды:

1. Отдельный коммит для всего проекта. Уместен, когда кодовая база небольшая, область действия ясна и команда может отдельно проверить массовые изменения.
2. Постепенное форматирование при изменении файлов. Подходит для большого проекта, если нет необходимости сразу приводить весь код к новым правилам. Зафиксируйте, что новые и изменяемые файлы должны соответствовать конфигурации.
3. Пилот на одном модуле. Используйте, если в репозитории много языков, каталогов или исторических исключений. После проверки результата расширяйте область действия.
4. Сначала проверка, затем обязательный CI. Подходит, когда важно подготовить команду: начните с информирующей проверки, устраните неясности и только затем включайте блокирующий статус.

В любом варианте просмотрите diff, запустите тесты проекта и отдельно проверьте, что изменения не вышли за согласованную область. Новое форматирование удобно отделить от функциональных правок отдельным коммитом.

Что делать с конфликтами настроек и форматирования

Что выбрать: форматтер или линтер?

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

Нужно ли включать форматирование при сохранении?

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

Как избежать массового изменения старого кода?

Начните с пилотного каталога или форматируйте файлы по мере изменений. Если приводите весь проект к новым правилам, отделите форматирование от функциональных правок.

Почему редактор и CI показывают разные результаты?

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

Стоит ли делать ошибку форматирования блокирующей в CI сразу?

Нет, если команда ещё не проверила локальный процесс и не разобралась с исключениями. Сначала запустите проверку без блокировки, затем сделайте её обязательной после согласования правил.

Что делать, если форматтер меняет файлы, которые не планировали затрагивать?

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

Автор: Наталья Орлова.