Обзоры кода не должны быть отстойными!

Как новичку поднять запрос на исправление (PR)

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

По данным Stack Overflow, причиной стресса номер один в жизни разработчика являются обзоры кода.

— Шутка!

Рецензирование кода или Pull Requests (PR) — это процесс совместной работы над фрагментом кода с целью:

1. Одобрить изменения
2. Запросить изменения
3. комментирования изменений

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

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

Отсутствие четкого рецензента, назначающего лица или титула

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

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

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

Отложенные обзоры

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

В больших командах часто можно увидеть, что PR находятся на рассмотрении слишком долго. Не часы, а дни. Команды должны прийти к соглашению об уровне сервиса (SLA) для рассмотрения PR. Это время, которое проходит с момента появления PR до его рассмотрения. Для одних это может быть 1 час, а для других — 5. Это устанавливает правильные ожидания для всех заинтересованных сторон.

Одним из основных инструментов, который я люблю, является Slack Reminders. Вы можете установить оповещения для всех ваших PR-специалистов, и он будет посылать небольшие напоминания на канал Slack. Подробнее об этом вы можете прочитать здесь: Управление запланированными напоминаниями для вашей команды.

Недостающие детали — шаблоны Pull Request

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

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

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

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

— Игорь Шарчевич

Под «необходимой информацией» я подразумеваю все детали, которые понадобятся рецензенту PR для тестирования PR. Это может быть:

1. Модуль, для которого PR вносит изменения
2. Некоторая предыстория — почему и как
3. JIRA Ticket, прикрепленный к PR
4. Необходимые шаги тестирования
5. Любые специфические изменения среды, которые должен сделать рецензент для рассмотрения PR.

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

Шаблоны Pull Request помогают напомнить разработчикам о необходимости заполнения необходимых деталей перед отправкой PR. Это может быть как простое напоминание о необходимости «самостоятельной проверки» PR, так и сложное — добавление файла .env и шагов тестирования.

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

Посмотрите, как легко теперь стало просматривать PR. По крайней мере, начните с обзора.

Повторяющиеся/пропущенные/игнорируемые обзоры

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

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

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

Средством решения этой проблемы является «система признания» для всех отзывов. Всякий раз, когда вы исправляете PR-отзывы и комментарии, просто оставьте 👍 (большой палец вверх emoji) или «Готово» в этом разговоре. Это займет не больше минуты, но поможет в двусторонней коммуникации.

Цель одиночного запроса на публикацию

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

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

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

Ни один PR не должен содержать более 400 строк кода — научно обосновано

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

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

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

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

Да, могут быть случаи, когда вы не сможете следовать этому кардинальному правилу 400 строк кода. Но поверьте мне, вы сможете. В статье Proof your thousand-line pull requests result in more bugs рассказывается о том, как можно рассыпать PR более чем на 400 строк кода и при этом не нарушить его.

Вкратце:

1. Выделите рефакторинг
2. Разложите основу PR на 1 части
3. Использовать флаги особенностей
4. Коммит по частям кода, а не по времени — это еще одна аналогия, которую привела Полин Вос в своем докладе Git Legit (Atomic commits will help you git legit). Если вы хотите прочитать больше об атомарных коммитах, загляните сюда.

Следите за своим тоном письма

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

НЕ ИСПОЛЬЗУЙТЕ ВСЕ КАПСЫ, чтобы показать, что вы расстроены и кричите (воображаемо).

Делайте комплименты, когда это необходимо.

Поблагодарите своего рецензента, когда длинный PR будет объединен после 3-4 переписок туда и обратно. Поблагодарите рецензента, если вы узнали что-то новое.

---

Спасибо, что читаете ❤

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

Первоначально опубликовано на adityatyagi.com

Хотите пообщаться?
Следите за мной в Twitter и LinkedIn или пишите в комментариях ниже!