Руководство по миграции стиля кода

Конвенции кодирования Kotlin и форматировщик IntelliJ IDEA

Конвенции кодирования Kotlin влияют на несколько аспектов написания идиоматического Kotlin, и среди них — набор рекомендаций по форматированию, направленных на повышение читабельности кода Kotlin.

К сожалению, форматировщик кода, встроенный в IntelliJ IDEA, был разработан до выхода этого документа, и сейчас имеет настройки по умолчанию, которые генерируют форматирование, отличное от рекомендуемого.

Может показаться логичным шагом устранить это несоответствие, изменив значения по умолчанию в IntelliJ IDEA и сделав форматирование согласованным с конвенциями кодирования Kotlin. Но это означало бы, что у всех существующих проектов Kotlin будет включен новый стиль кода в момент установки плагина Kotlin. Не совсем ожидаемый результат для обновления плагина, не так ли?

Вот почему вместо этого у нас есть следующий план миграции:

• Включить форматирование стиля кода по умолчанию, начиная с Kotlin 1.3, только для новых проектов (старое форматирование можно включить вручную)
• Авторы существующих проектов могут выбрать миграцию на конвенции кодирования Kotlin
• Авторы существующих проектов могут явно указать использование старого стиля кода в проекте (таким образом, проект не будет затронут при переключении на значения по умолчанию в будущем)
• Переключиться на форматирование по умолчанию и сделать его согласованным с конвенциями кодирования Kotlin в Kotlin 1.4

Различия между «Конвенциями кодирования Kotlin» и «Стилем кода по умолчанию IntelliJ IDEA»

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

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

Обсуждение миграции на новый стиль кода

Принятие нового стиля кода может быть очень естественным процессом, если он начинается с нового проекта, когда код не отформатирован старым способом. Именно поэтому, начиная с версии 1.3, плагин Kotlin IntelliJ создаёт новые проекты с форматированием из документа «Конвенции кода», который включён по умолчанию.

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

Основным недостатком изменения стиля кода в существующем проекте является то, что функция отслеживания изменений/комментирования системы контроля версий (VCS) будет чаще указывать на нерелевантные коммиты. Хотя каждый VCS имеет какой-то способ решения этой проблемы ("Просмотреть предыдущую ревизию" можно использовать в IntelliJ IDEA), важно решить, стоит ли новый стиль всех усилий. Практика разделения коммитов по переформатированию и значимым изменениям может очень помочь в последующих исследованиях.

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

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

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

Миграция на новый стиль кода

Переход к стилю кода «Конвенции кодирования Kotlin» можно выполнить в диалоговом окне Settings → Editor → Code Style → Kotlin. Переключите схему на Проект и активируйте Set from... → Predefined Style → Kotlin Style Guide.

Чтобы поделиться этими изменениями со всеми разработчиками проекта, .idea/codeStyle папку необходимо добавить в систему контроля версий.

Если используется внешняя система сборки для настройки проекта и было принято решение не делиться .idea/codeStyle папкой, конвенции кодирования Kotlin можно принудительно включить с помощью дополнительного свойства:

В Gradle

Добавьте свойство kotlin.code.style=official в файл gradle.properties в корне проекта и добавьте файл в систему контроля версий.

В Maven

Добавьте свойство kotlin.code.style official в корневой файл проекта pom.xml.

<properties>
  <kotlin.code.style>official</kotlin.code.style>
</properties>

Предупреждение: наличие параметра kotlin.code.style может изменить схему стиля кода во время импорта проекта и может изменить настройки стиля кода.

После обновления настроек стиля кода активируйте «Переформатировать код» в представлении проекта на желаемом уровне.

Для постепенной миграции можно включить проверку «Файл не отформатирован в соответствии с настройками проекта». Она выделит места, которые нужно переформатировать. После включения опции «Применять только к изменённым файлам», проверка будет показывать проблемы форматирования только в изменённых файлах. Такие файлы, скорее всего, будут вскоре коммитированы.

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

В любой момент можно явно установить стиль кода IntelliJ IDEA в качестве правильного стиля кода для проекта. Для этого переключитесь на схему Проект в Settings → Editor → Code Style → Kotlin и выберите "Устаревший стиль кода IntelliJ IDEA для Kotlin" в "Использовать значения по умолчанию из:" на вкладке Загрузка.

Чтобы изменения применялись для всех разработчиков проекта, .idea/codeStyle папку необходимо добавить в систему контроля версий. В качестве альтернативы можно использовать kotlin.code.style=obsolete для проектов, настроенных с помощью Gradle или Maven.