Проверка кода может быть болезненной, но не обязательно

Проверка кода может быть болезненной. Инженеры-программисты часто жалуются, что процесс рецензирования идет медленно, задерживает последующие задачи и приводит к переключению контекста, когда вы переключаетесь между открытым запросом на вытягивание (PR) и следующей задачей. Обзоры кода также могут быть полны придирок и придирок, что делает его плохим опытом для всех участников.

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

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

# 1: Держите запросы на слияние небольшими

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

Решение состоит в том, чтобы ваши пулл-реквесты были небольшими. Небольшие PR легче и быстрее просматривать, потому что рецензенту не нужно тратить столько времени на построение мысленной модели того, как все изменения работают вместе. Также меньше изменений в коде, что, как мы надеемся, соответствует меньшему количеству ошибок, меньшему количеству комментариев и меньшему количеству кругов между автором и рецензентом.

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

Держите ваши PR небольшими. Ваши рецензенты будут благодарны.

# 2: Используйте шаблоны запросов на вытягивание

Еще одна неприятность заключается в том, что вас просят просмотреть запрос на вытягивание без какого-либо контекста. Когда PR падает вам на колени без объяснения причин, вы часто задаетесь вопросом: «Для чего этот PR? Какую проблему это решает? Есть ли связанная задача для этого? Почему был выбран именно этот подход?»

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

Хорошие PR-шаблоны также обычно включают краткий контрольный список, который автору кода нужно пройти, чтобы убедиться, что он не упустил ни одной из основ. Этот контрольный список может включать такие элементы, как модульные тесты, документы, интернационализация, кросс-браузерная поддержка и доступность.

Ниже приведен пример шаблона запроса на вытягивание, который мне нравится использовать для всех моих репозиториев:

# 3: Внедрите SLA для времени отклика

Если вы обнаружите, что запросы на вытягивание остаются без рассмотрения дольше, чем вам хотелось бы, сейчас самое время установить ожидания всей команды относительно того, как быстро должен быть рассмотрен новый запрос на вытягивание. Другими словами, каково максимальное количество времени, в течение которого может существовать PR, прежде чем его нужно будет забрать? Один час? Два часа? 24 часа? Ваш ответ на этот вопрос, скорее всего, будет зависеть от размера вашей команды. У вас также могут быть разные ответы на внутренние запросы на вытягивание от вашей команды и на внешние запросы на вытягивание от других команд.

Выбирая SLA (соглашение об уровне обслуживания) о времени отклика, вы должны найти правильный баланс. Неразумно ожидать, что все немедленно бросят все, что они делают, и просмотрят ваш код, когда вы опубликуете новый PR, но вы также не хотите, чтобы PR оставались непросмотренными в течение нескольких часов подряд. Найдите правильный баланс, который позволит вашим товарищам по команде войти в состояние потока. Они должны иметь возможность работать над своим собственным кодом, а затем просматривать PR в естественных точках остановки в течение дня.

Лично мне нравится иметь SLA с двухчасовым временем отклика для внутренних командных PR и 24-часовое SLA для внешних командных PR.

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

#4: Обучайте младших и средних инженеров

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

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

Существует множество отличных ресурсов о том, как стать более эффективным рецензентом кода. Руководство разработчика по проверке кода от Google стоит прочитать полностью. В руководстве есть отличные советы как для автора кода, так и для рецензента кода. Если говорить о более дерзком ресурсе, то Как влюбить в себя рецензента кода — один из лучших (и занимательных) советов для разработчиков, создающих пулл-реквесты.

# 5: Настройте конвейеры непрерывной интеграции

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

Для проектов JavaScript легко настроить средство форматирования, например Prettier, и линтер, например ESLint, для вашего репозитория. Затем вы можете настроить непрерывную интеграцию для своего репозитория, используя что-то вроде Travis CI, CircleCI, GitHub Actions или GitLab CI/CD.

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

Теперь вы автоматизировали несколько важных частей проверки кода, сэкономив часы.

# 6: Используйте приложения для проверки запросов на слияние

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

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

# 7: Создавайте диаграммы для визуализации изменений вашего кода

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

CodeSee Review Maps поможет вам визуализировать, какие файлы были изменены и как эти изменения влияют на их исходные и последующие зависимости. Они интегрируются с GitHub, чтобы автоматически публиковать комментарий и диаграмму в вашем PR. Вы даже можете создавать интерактивные туры по своему коду, чтобы помочь вашим рецензентам. Лучше всего то, что карты CodeSee Maps бесплатны для организаций с открытым исходным кодом и их общедоступных репозиториев.

Заключение: рекомендации по ускорению проверки кода

Подводя итог, вот семь советов, как значительно сократить время проверки кода:

  1. Держите пул-реквесты небольшими.
  2. Используйте шаблоны запросов на вытягивание, чтобы предоставить весь контекст, который может понадобиться рецензенту.
  3. Внедрите SLA по времени отклика.
  4. Обучайте младших и средних инженеров ключевым вещам, на которые вы обращаете внимание во время проверки кода.
  5. Настройте конвейеры CI для запуска линтеров, средств форматирования и модульных тестов.
  6. Используйте приложения для проверки запросов на вытягивание, чтобы вы могли легко проверять изменения пользовательского интерфейса.
  7. Создавайте диаграммы для визуализации изменений кода с помощью таких инструментов, как CodeSee Review Maps.

Спасибо за чтение и удачного кодирования!