За всю свою карьеру я изучил тысячи пул-реквестов. Из этого опыта родилось несколько советов. Я надеюсь, они помогут вам создать обучающую среду, дружелюбную к новичкам и милостивую к ревьюерам. Сначала позаботимся о новичках...
Советы для автора
Маленькие, итеративные кусочки. Не пихайте слишком много в один пул-реквест. Это подарит ревьюеру возможность своевременно и с высокой пропускной способностью просматривать код.
Конечно, гораздо проще добавить кучу несвязанной работы в один-единственный пул-реквест, и все же постарайтесь этого не делать.
Пользуйтесь ярлыками. Неважно, что именно вы используете — префиксы перед темой сообщения или встроенное тегирование — главное, щедро этим пользуйтесь! Такие пометки нужны, чтобы сообщить о статусе работы, объеме ревью или указать, к какому этапу относится пул-реквест.
Обеспечьте ясный контекст. В описании проекта укажите, над какой проблемой вы поработали и какое решение предложили. Тогда и код-ревью проще делать, и других будет легче ввести в курс дела.
Делайте ревью собственных коммитов. Делайте ревью собственных пул-реквестов, как только те появились на свет — так вы избавитесь даже от намека на двусмысленность. Обеспечьте ревьюера подробным комментарием к самым мутным строчкам кода.
Всегда, всегда будьте открыты для обратной связи. Вероятно, у ревьюера благие намерения. Потому доброжелательно реагируйте на его критику, задавая наводящие вопросы и тут же внося правки. Если есть необходимость отсрочить правки, то сделайте это, но заверьте ревьюера в том, что вы согласны с его критикой.
Полезное код-ревью — это доброжелательное код-ревью. С этими словами перейдем к советам для ревьюеров.
Советы для ревьюера
Фиксируйте все обсуждения. Вокруг пул-реквестов всегда много разговоров, но только они нигде не записываются. В итоге эта информация просто не добирается до остальных участников проекта.
Исправьте это. Фиксируйте ваши обсуждения, чтобы обеспечить команду ясным контекстом для работы.
Завершайте ревью утверждением и комментарием. Подведите итог в конце ревью, написав небольшой абзац. Так вы обеспечите обратную связь, поддержите автора пул-реквеста и наладите с ним доверительные отношения.
Подробное ревью это залог эмоциональной привязанности. Покажите свою заботу и о коде, и о его авторе. Прикрепите свои предложения для правок. Такое отношение к код-ревью обеспечивает развитие дружных команд. Кстати о командах...
Советы для команды
Работа в парах лучше чем пул-реквесты. Работа в парах это почти то же самое, но только гораздо быстрее. Разработайте такую систему, в которой пара программистов может легко и быстро начать совместную работу.
Сделайте код-ревью доступным. Обеспечьте новичков своевременным код-ревью. Я видел команды, которые добиваются этого через установление конкретных сроков, некоторые даже прописывают их в SLA (соглашение об уровне сервиса).
Неважно, что вы используете — главное помните, среда должна быть инклюзивной и доброжелательной. Если новичок вынужден постоянно напоминать о себе ревьюеру, это плохо.
Автоматизируйте мелочевку, которая отвлекает ревьюера. Ревьюер с высокой пропускной способностью в своей работе думает об общем направлении кодовой базы, а не о всяких мелочах вроде форматирования. Поэтому автоматизируйте такие мелочи всегда, когда это возможно.
Внедряйте списки дел. Пул-реквесты прекрасны потому, что дарят команде море идей для развития. Не надо просто любоваться этими идеями, добавьте их в список дел. И претворите эти идеи в жизнь на следующей итерации!
Создайте чек-лист. Некоторые команды разработали целую философию вокруг правильного форматирования пул-реквестов. Другие пошли дальше и составили чек-листы, по которым надо пройтись перед утверждением пул-реквеста. Сделайте так же — найдите способ добиться от команды полной ясности в отношении код-ревью.
Обеспечьте стабильную сборку. Проверьте, все ли работает, если запустить проект локально. Я не знаю, что вы предпочитаете — pre-commit, статический анализ кода или тесты — но знаю, что вам просто необходимо обеспечить стабильную сборку в одно касание.
К черту совершенство. Помните, что важнее всего для разработчика — это не совершенство, а здоровая кодовая база, понятная всей (всей!) команде. Поэтому не стоит расстраиваться, когда с новичками возникают трудности; вместо этого сфокусируйтесь на общем росте и развитии, которое обеспечивает практика код-ревью.
Помните, что в вашей команде работают только инженеры, вообще на всех ее уровнях. Чтобы они смогли развиваться, придется перетерпеть и трудные моменты тоже.
Пул-реквесты — это как бы обучение по типу перекрестного опыления. Уважайте усилия контрибьюторов, поскольку контекст и диалог рулят разработкой ПО. Донесите до автора то, как искренне вы в это верите. А также помните, что...
- Ясные взаимные ожидания — это основа плодотворного сотрудничества.
- Новички могут стать основными контрибьюторами вашего проекта.
- У код-ревью есть бонусы — это отлов багов и цельный код.
И наконец...
Получайте удовольствие. Однажды я видел команду, которая писала все саммари в форме хайку или в изящной прозе. В итоге у них получилась команда отпетых Хеммингуэев! Почему бы вам тоже не включить в практику что-нибудь эдакое? Ведь разработка — это прежде всего про любознательность и про обучение в ходе игры.
Это перевод статьи Дага Аркури (Doug Arcuri). Оригинальная статья: Be a Rock Star at Pull Requests. Tips for a successful collaborative code review.
Я сохранила все ссылки Аркури из оригинальной статьи. Ссылки по github milestones и SLA — от меня.
Любая критика перевода — велкам!
