7 советов, как сделать Code Review легким и полезным

Приветствую! Меня зовут Михаил и я фронтенд-разработчик с опытом коммерческой разработки более 6 лет. Я разрабатывал веб-приложения для стартапов, финтеха и продуктовых компаний. На данный момент я тружусь в компании Miro. Наша компания разрабатывает сервис бесконечной доски (endless whiteboard) для совместной работы распределенных команд, проведения воркшопов и многого другого.

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

Что такое Code Review

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

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

Почему Code Review — это сложно и долго

Входной точкой для ревью является Pull Request (PR). PR — это запрос на слияние ваших изменений кода, которые расположены в отдельной ветке, в главную ветку проекта. Именно в этом запросе и происходит ревью вашего кода, поэтому простота и качество Code Review зависит не только от самого кода, но и от того, как оформлен PR.

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

Пример того, как не нужно называть пул-реквесты

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

В дополнении к первой проблеме, важно выделить историю разработки. Любой крупный проект со временем обрастает легаси-решениями, с которыми работают новые программисты. Одним из способов понять, зачем был написан тот или иной код, это посмотреть, кем он был написан и каким пул-реквестом влит в кодовую базу (Blame view). Очень печально в таком случае сталкиваться с пустыми PR с названиями по типу — «Small fix» или «Update module».

Вторая проблема Code Review — это, естественно, сам код. Мы не будем говорить о качестве и глубине самого решения задачи, так как это зависит от квалификации разработчика, но даже хорошо написанный код может надолго задержаться на ревью по таким причинам: большое количество изменений (20-30 и более файлов), лишний рефакторинг кода, несоблюдения стиля оформления кода и прочее.

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

1. Главное правило — цените время ревьювера

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

Первый ревьювер — это вы

Просто представьте, как будто вы читаете свои изменения первый раз. Для этого достаточно открыть git diff changes вкладку (поддерживается большинством популярных IDE).

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

2. Оформите Pull Request

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

Название

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

Большинство систем контроля версий поддерживают интеграцию с сервисами ведения проектов (jira и т. д.). Используйте это для того, чтобы в названии указать ID задачи, которая автоматически станет ссылкой, что позволит в один клик перейти в задачу и узнать больше информации о работе, которую вы провели

Описание

В описании к PR напишите кратко, что ваш код привносит или какое решение содержит.

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

Пример отличного Pull Request

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

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

Loom видео или любой скриншотер поможет быстро создавать такие демо.

3. Минимизируйте изменения

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

10000 новых строк потребуют огромных усилий для ревью

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

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

4. Делайте рефакторинг отдельной задачей

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

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

5. Отделяйте важные шаги разработки в отдельные коммиты

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

Но не стоит создавать коммиты на каждый новый файл или небольшой фикс. Для этого используйте Squash или Amend, перезаписывая старые коммиты с новыми изменениями или сливая несколько коммитов в один.

6. Не смешивайте изменения стиля кода с функциональным изменением

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

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

Пример нефункционального изменения кода

7. Ваш PR — это письмо в будущее

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

Как пример, существует чудесное расширение для VSCode под названием GitLens, которое позволяет посмотреть историю изменений в редакторе.

Просмотр истории коммитов по каждой строке

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

Это косвенно относится в ревью, но очень полезно в будущей работе. Представьте, если вы будете читать полное описания коммитов, PR вместо «small fix», «chore: update» и т. д.

Заключение

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