Ревю это что в айти
Что такое код-ревью
Это проверка кода на ошибки, неточности и общий стиль программирования.
Послушать аудиоверсию этой статьи (6 минут):
Слушайте Что такое код-ревью на Яндекс.Музыке
Ситуация: вы разработчик. Вы отвечаете за свой фронт работы, например, за отправку данных на сервер. У команды уже есть готовый проект, вы вместе его поддерживаете и постоянно улучшаете.
Когда вы пишете новую функцию, она не попадает сразу в проект. Вместо этого ваш код отправляется на код-ревью (code review).
Что делают на код-ревью
Во время код-ревью кто-то из старших товарищей изучает ваш код на предмет:
Если проблемы есть, проверяющий отправляет код на доработку. Если всё хорошо, код переходит на следующую стадию — как правило, в тестирование.
Кто проводит
Обычно принято так: код-ревью делают программисты более старшего уровня. Джуниоров проверяют мидлы, мидлов — сеньоры, сеньоров — другие сеньоры или тимлиды. Если компания большая, то могут выделить отдельно несколько человек, которые смотрят код у всех и следят за общим стилем.
Если команда небольшая, то код-ревью делает ведущий программист — он сам следит за проектом и за качеством кода, который пишут остальные.
Как это выглядит
Зачем это нужно
Если вы пишете один или с другом, то, скорее всего, вам это не нужно. Вы и так можете обсудить код между собой и понять, как его сделать лучше.
Когда в команде программистов много, то компания сталкивается с тем, что все пишут по-разному. И даже если весь этот код работает, его потом нужно поддерживать, а ковыряться в чужом коде, если он плохо написан — это долго и дорого. Поэтому на этапе код-ревью разработчики делают так, чтобы им же позднее было проще поддерживать код и ничего не ломалось.
Код ревью, как внедрить и не испытывать боль
Если вы работаете в продуктовой компании, то жизненный цикл почти каждого продукта будет соответствовать принципу Парето:
20% времени мы пишем новый код.
80% времени поддерживаем старый. Поддержка в себя включает фиксы багов, обновление кодовой базы (переезд на новые библиотеки например).
Во время поддержки мы хотим чтобы все разработчики как можно быстрее вникали в то, что написано. Для этого есть много способов, все они прекрасны и хорошо работают вместе.
Способы иметь хорошо поддерживаемый код:
Все эти способы нужно уметь готовить. Есть тесты, которые только мешают, бесполезная документация и бессмысленный код ревью.
Что же такое код ревью?
Что нам даёт код ревью:
Проверку кода по многим критериям.
Автор не всегда видит неочевидные места в его коде (по разным причинам).
В результате написания и переписывания может быть потеряна композиция.
Автор, находясь в контексте задачи может недостаточно оставить комментариев.
Эти и многие другие проблемы может решить код ревью.
Шаринг знаний о проекте.Не только автор знает, что там пишется в другом проекте или части проекта, а все.
Шаринг знаний о технологиях.Вы можете заметить, что кто-то напилил своих костылей, а похожая проблема в проекте уже решалась. В таком случае ревьюер может подсказать что уже использовалось и избежать ненужного кода
Сотрудники быстрее онбордятся. Новые сотрудники, проводя код ревью, быстрее узнают и понимают традиции команды, а проходя его, имеют возможность исправить ошибки, узнать больше о продукте и меньше испытывать стресс.
Способов поддерживать код «качественным» есть много, но все их нужно правильно готовить. Нужно уметь писать тесты, нужно уметь писать документацию и нужно правильно организовать код ревью.
Советы по организации процесса
Условные обозначения:
— Как делать не нужно
+ Как делать нужно
- Ревьюить только джунов и новых коллег
+ Проводить ревью для всех и всеми
Если ревью проходят не все, то в вашей команде это будет восприниматься как источник недоверия и неравенства. Такую атмосферу следует избегать.
- Обсуждать на код ревью стиль
+ Настроить у себя на проекте инструменты, которые автоматически будут исправлять стиль перед коммитом
В JS это eslint и prettier. Не тратьте время своё и коллег на споры о вкусах. Договоритесь заранее и пропишите правила. В случае разногласий голосуйте.
Не обсуждайте стиль на ревью
- Ревьюер запускает руками билд или проверяет код на баги.
+ Автор сам несет ответственность за поставленный код.
Автор тщательно проверил свой код на работоспособность и залил в удаленный git репозиторий
На сервере CI/CD проверяет тесты, сборку, работоспособность в целом.
Проверка со стороны ревьюера.
- Ревьюер не читает код
+ Обращать внимание на композицию, магические переменные, оптимизацию (там где это имеет смысл)
Обращайте внимание на код ревью.
- Агрессия, негатив, «токсичное» поведение в комментах
+ Старайтесь отмечать не только негативные стороны, но и хвалить за позитивные.
Агрессия, негатив и токсичное поведение в принципе стоит избегать во всех областях жизни. Грубое поведение во время код ревью может привести к:
Стрессу и страху совершить ошибку
Примеры плохих комментов:
Примеры хороших комментов:
«Давай попробуем сделать …» «Может попробуем вынести…»
То же самое касается и ответов на комменты автором. Если автор не согласен, то необходимо объяснять с помощью аргументов, а не фраз в духе «я так делать не буду». Если не получается текстом, иногда проще подойти или сделать короткий созвон, чтобы понять друг друга.
Чаще хвалите код в ревью
- Все комментарии обязательны к исправлению
+ Помечать необязательные комментарии
Пытаться объяснить алгоритмы на словах
Написать пример псевдокода
Особенно актуально, если автор не совсем понимает что от него хочет ревьюер. Не нужно полностью писать реализацию. Напишите небольшой пример псевдокода. Gitlab, github и bitbucket позволяют вставлять в комментарии разметку markdown. Ваш код будет хорошо отформатирован и более понятен, чем длинная цепочка комментов.
- Оставлять больше 50 комментариев
+ Оставлять до 50 комментариев
Если комментариев накапливается очень много, то у вас:
Или не настроены линтеры, и вы не определились со стилем, поэтому комменты о вкусовщине
Или переделать в коде нужно многое
Во втором случае оставьте 1 комментарий с рекомендациями как и что нужно переписать. В таком случае лучше закрыть мердж реквест, переписать код и открыть новый.
Если код будет переписан полностью, отследить изменение по комментариям практически невозможно и они не имеют смысла. Авторы тоже должны это понимать и следить, чтобы всем было комфортно.
- Отправлять огромные фрагменты кода на ревью
+ Дробить большие участки кода на несколько реквестов и вливать постепенно
Задачи бывают разными по объему. Может быть задача исправить 1 строчку кода, а может быть задача отрефакторить весь проект. Во втором случае не отправляйте реквест в котором исправлены 500 файлов и 4000 изменений. Никто в здравом уме не сможет это нормально проверить, и желания такое проверять вы тоже не найдете.
Сделайте ветку feature/epic-name
Изменения делайте в ветке feature/epic-name-implement
Pull реквесты делайте в ветку feature/epic-name. Порционно.
В конце реализации фичи подлейте feature/epic-name в мастер. Да, в этом случае пулл реквест тоже будет огромный, но всё уже будет заранее проверено
Другой вариант как этого избежать: feature flags. Вы вливаете изменения на прод, но не даете им пользоваться. Нормально это реализовано мало у кого. Поэтому с этим подходом нужно быть осторожнее.
Уважайте тех, кто будет проверять ваш PR
- Pull Request висит без ревью трое суток
+ Выработать расписание
Среди аргументов против код ревью вы услышите, что с ним у вас увеличивается время «доставки» фич. Чтобы этого не происходило, выработайте у ревьюеров расписание. Например, новые реквесты проверять до работы и перед уходом домой, а исправленные в перерывах в течении дня (например пока проект собирается или тесты гоняются).
В заключении
В этой статье я хотел рассказать и показать плюсы проведения код ревью. Будучи старшим разработчиком я всегда за то, чтобы мой код проходил code review. Лично для меня это отличный способ “увидеть” свой код чужими глазами. еще до того как ветка отправляется на ревью. Не говоря уже о том, что для команд это недорогой и эффективный способ иметь кодовую базу, с которой можно будет эффективно работать.
Если в вашей команде нет код ревью, то самое время его внедрить .
Ссылки и благодарности
По теме рекомендую почитать:Статья How to Do Code Reviews Like a Human
Спасибо лису и kirjs из @learnInPublic за ревью статьи про ревью.
Что такое код-ревью и кто им занимается?
Эффективный способ заботиться о качестве кода
Проверка кода — это как базовое правило гигиены. Разработчики могут создавать запутанный и тяжелый код. Его сложнее обслуживать, а сбои появляются там, где не ждешь. Поэтому важная часть работы над продуктом — код-ревью, когда более опытные разработчики проверяют качество кода. Мы поговорили с Андреем Строговым, который руководит код-ревьюерами в Яндекс.Практикуме, о главных качествах такого профессионала и бесполезных комментариях к коду.
Задачи код-ревьюера
Код-ревью — это этап разработки кода. Чаще всего его проводят другие разработчики из той же команды. Так более опытные кодеры контролируют качество работы джуниоров или стажеров. Ревьюер на отдельных компонентах может показать, как сделать код проще и понятнее. Например, предложит взять функцию, которая уже написана для другого фрагмента. Проверка кода особенно важна для работы больших команд.
«В масштабных проектах код очень объемный и каждый разработчик знает только свой фрагмент. Люди часто не в курсе, что происходит в других компонентах и модулях. Это не слишком устойчивая ситуация, потому что автор кода может уйти в отпуск или по разным причинам перестать поддерживать свой фрагмент. Этап код-ревью добавляет второго человека, который понимает код и может с ним работать», — говорит руководитель команды код-ревью Андрей Строгов.
Код-ревью — это хороший способ договориться внутри команды, как писать код. Например, запутанный код сложно поддерживать в рабочем состоянии и масштабировать. Этап код-ревью помогает обмениваться знаниями, находить новые решения, делать лучше весь процесс разработки.
В отличие от тестирования, на код-ревью важнее разобраться в логике решения, чем найти ошибки. А еще — донести суть проблемы до разработчика. Для этого понадобится умение точно формулировать проблему и сообщать о ней без лишних эмоций.
«Когда мы проверяем код, не надо тратить время на мелкие ошибки — названия переменных, опечатки. Это плохо влияет и на того, кто пишет код, и на проверяющего. В первую очередь автору нужна обратная связь по логике кода. Проверку мелких ошибок легко автоматизировать», — говорит Андрей Строгов.
Этапы работы и инструменты
Код-ревьюер движется от общего к частному. Сначала ему нужно понять, какую задачу решал автор кода. Для этого проверяющий смотрит техническое задание и уточняет детали у разработчика. Дальше нужно оценить архитектуру кода и посмотреть, грамотно ли он написан. Это самый ценный этап код-ревью, он помогает избежать грубых ошибок и сэкономить время команде тестирования.
Когда ревьюер разобрался с задачей и логикой решения, он смотрит на функции, отдельные алгоритмы и их эффективность. Проверяет, можно ли заменить их другими методами и будет ли это лучше для всего продукта.
«На этих этапах не нужно никаких специальных инструментов. Только экспертные навыки и знание задачи. Код-ревьюеру понадобятся некоторые инструменты среды лишь для того, чтобы посмотреть, как работает код, и обнаружить грубые ошибки», — говорит Андрей Строгов.
После проверки ревьюер оставляет комментарии для разработчика. Его задача на этом этапе — объяснить, почему важно исправить ошибку. А еще проверяющий может подсказать решение или дать ссылки на материалы, с которыми разработчик быстрее приведет код в порядок. Весь процесс проверки не должен тормозить остальную разработку — хорошо, если код-ревью удается закончить за время рабочего дня.
«Наша задача в том, чтобы разработчик понял, в чём заключается комментарий и почему важно исправить код в соответствии с ним. Для этого недостаточно сильных технических знаний, нужны хорошие soft skills. Если ревьюер дал полезный комментарий, а разработчик почему-то не захотел исправлять — это будет выглядеть глупо», — говорит Андрей Строгов.
Полезный комментарий помогает исправить и улучшить код. А еще в нём нет субъективной оценки или нотаций. Поэтому критически важно, чтобы код-ревьюер умел давать качественную обратную связь. Иначе автор примет замечания на свой счет, и никакой эффективной работы не получится.
«Не стоит оставлять комментарии в духе “бред какой-то” или “тут ты не подумал”. Нужно формулировать проблему корректно. Субъективное мнение тоже не помогает улучшить код. Лучше найти что-то точнее, чем “это непонятный код”», — говорит Андрей Строгов.
Кроме комментариев код-ревьюер может оставлять рекомендации. Это некритичные замечания, их можно взять в работу, если у разработчика останется время. Например, проверяющий видит, что код выглядит запутанным. Задача решена, и весь функционал в порядке, но кажется, что работа сделана небрежно. Тут можно обойтись рекомендацией — обратить внимание человека на эту особенность его решения.
«Вы сэкономите время команде, если выделите критичные замечания. Это замечания, касающиеся фрагментов, которые могут привести к некорректной работе кода или помешают расширить его в будущем. Еще сюда относятся ошибки, из-за которых код трудно поддерживать и редактировать», — говорит Андрей Строгов.
Знания и навыки
Чтобы проверять код, нужно в нём разбираться. Хорошо, чтобы ревьюер уже решал такие задачи, писал подобный код и был знаком с тем стеком технологий, который используют в команде. Тогда ревьюер сможет дать разработчику полезные комментарии.
«Нужно отучить себя от того, что ты обязательно должен написать комментарии после ревью. Если с кодом всё в порядке, он может вернуться к автору без замечаний, которые оставляют ради самих замечаний», — говорит Андрей Сторогов.
Важно смотреть на код с позиции автора. У ревьюера может быть свой способ работы с кодом или другое решение для конкретной задачи. Но вся ценность его работы — предложить улучшения, ориентируясь на методы работы автора кода.
«Для команды хорошо, когда ревьюер может искренне похвалить удачное решение, — говорит Андрей Строгов. — Разработчики делятся на две категории. Одни считают, что пишут идеальный код, другие — что их код плох. Поэтому важно научиться искренне хвалить за хорошие решения. Это приятно автору кода и укрепляет отношения в команде».
Стать хорошим ревьюером помогает практика. Если в вашей команде пока нет такой деятельности, можно искать подходящие проекты на GitHub и оставлять комментарии там. «Код-ревью влияет на качество кода уже самим фактом своего существования, —говорит Андрей Строгов. — Когда знаешь, что твой код посмотрят, тщательнее к нему относишься. Например, постараешься его понятно оформить, не будешь использовать запутанную логику, в которой не смог бы разобраться другой разработчик. Это полезная социальная составляющая, которая мотивирует делать более понятный код».
Ревью кода в распределенной команде
Здесь описаны мои исследования, как сделать ревизию кода в команде более приятным занятием, которое может дать новый опыт всем участникам. У нас полностью географически распределённая команда, все коммуникации выполняются через интернет, и зачастую асинхронно. Мы используем Trello для описания возможностей продуктов, поодиночке создаём код, отправляем в GitHub пулл-реквесты, а также пользуемся встроенной в GitHub функцией их ревью. Это отличается от просмотра кода лицом к лицу в офисе и даже по видеочату.
Если не подходить к делу всерьёз, то асинхронная и письменная ревизия кода может стать причиной катастрофы в команде, приведя к ухудшению взаимодействия и сотрудничества. Но если все участники будут стараться делать всё хорошо, то такой подход может работать очень эффективно.
Для чего нужно ревью кода?
Прежде чем начать рассуждать о том, как делать и как не делать ревью, полезно подумать о том, для кого в компании оно нужно, и в соответствии с этим вырабатывать требования. И хорошо бы не забывать, что ревью — это не просто поиск багов и проблем в структуре кода.
Ревью нужно для улучшения качества кода и морального духа в команде.
Анализ кода друг друга — один из главных путей взаимодействия между разработчиками во время обычного рабочего дня. Это должен быть вдохновляющий процесс, чтобы все участники ждали его и активно участвовали в нём.
Вот основные задачи, решаемые с помощью ревизий:
Что не надо делать при ревью
Возможно, эта часть покажется вам довольно негативной, но зато после неё идёт часть с приятными вещами!
Есть много разных способов сделать ревью кода неудачным. Воинственные, злые и непредсказуемые комментарии способны лишить команду удовольствия от работы и превратить ревизию в эмоционально тяжёлую обязанность.
Понимание, чего следует избегать при ревью, как раз и отличает ценную часть работы команды от жестокого и неприятного наказания. Эрик Дитрих, «Чего нужно избегать при ревью кода»
Не проводите ревью формально и с минимальными комментариями
(aka узнать, насколько плохо думают о вас коллеги)
Не нужно всего лишь указывать на ошибки, ничего к этому не добавляя.
Разработчики тратят много времени на код и гордятся им, и ревью — их шанс продемонстрировать свою работу. А при формально-минималистичном подходе всё, на что вы можете надеяться, — это комментарии в стиле «Выглядит неплохо, смерджил». Такое ревью достойно названия «Узнай, насколько плохо о тебе думают».
Не думайте, что достаточно лишь «критиковать код, а не кодера»
Это один из самых популярных советов: критикуйте код, а не кодера. Он хорош (если вы критикуете коллегу, а не его код, то у вас проблемы). Но этого недостаточно. Написание кода — творческий процесс, в который разработчик вкладывает сердце и душу. И если вы жестоко и тупо критикуете чей-то код, то тем самым вы критикуете самого человека. Нужно уметь критиковать. Найдите более позитивные способы анализа и вносите свои предложения, как улучшить код.
Следите за тоном
Не переходите на личности. Фразы вроде «Почему ты сделал именно так?» воспринимаются как нападки. Плохой вариант: «То, как ты написал эту функцию, затрудняет её чтение, добавь больше комментариев» (личное обращение подразумевает, что человек что-то сделал не так). Лучше скажите: «Тебе не кажется, что стоит добавить в код дополнительные комментарии, это облегчит чтение функции?» (звучит гораздо корректнее и позволяет сосредоточиться на улучшении кода).
Обойдитесь без требовательных или вызывающих выражений. Избегайте фраз, смысл которых заключается в «ты неправ». Не говорите людям, что они неправы или что они сказали/сделали что-то не то, им будет неприятно. В таких случаях люди могут уходить в защиту, перестают долго и творчески работать и учиться. Избегайте фраз наподобие:
Не надо оскорблений. Избегайте ругательств вроде «дурак» или «идиот», даже если лично вы не считаете их обидными. У подобных слов есть определённый спектр значений, и он точно не улучшит настроение автора кода.
Не используйте нетерпеливых или пассивно-агрессивных оборотов. Всегда будьте сдержанны и дружелюбны, избегайте неприятных фраз, демонстрирующих раздражение и заставляющих людей чувствовать, что они плохо справляются:
Не будьте непрошеным советчиком
Сдерживайте себя и не предлагайте внести в код все изменения, которые вы хотели бы внести. Вы можете деморализовать автора кода, предложив поменять столько, что придётся всё переписать. Так что выбирайте только самое важное и лучшее.
Одна из задач ревью — найти и исправить баги и проблемы в структуре кода. А вовсе не заставить автора написать код так, как это сделали бы вы. Не забывайте, что в программном обеспечении многие вещи можно решить по-разному, в зависимости от вкусов разработчика, и у каждого подхода есть свои плюсы и минусы. Собираясь предложить очередную правку, спросите себя: может быть, это просто моё мнение? Если автор выбрал другие способы, обосновав свой выбор, то лучше поддержите его. Уважайте право автора на собственные решения.
Даже если кто-то написал код не так, как это сделали бы вы, то это ещё не означает, что код написан неправильно. Главное — качественный, удобный в сопровождении код. Если он удовлетворяет этим критериям и принятым в команде правилам, то этого достаточно. Роберт Бог, «Эффективные ревью без боли»
Вы никогда не сможете заставить других написать именно такой код, какой написали бы вы, не надо и пытаться (если вам это так важно, то лучше сразу напишите код сами). Эрик Дитрих, «Чего нужно избегать при ревью кода»
Не нарушайте правило «Никаких сюрпризов»
Избегайте неожиданностей. Создайте для команды общее задокументированное соглашение о pull request’ах и стандартах кода и во время ревью опирайтесь на него, а не на своё мнение.
Не говорите только для того, чтобы услышать свой голос
Прежде чем написать отзыв, подумайте, чего вы хотите этим достичь. Все ли ваши комментарии необходимы? Помните, что вы пытаетесь конструктивно помочь, а не просто высказать свою точку зрения. Прежде чем опубликовать отзыв, перечитайте свои комментарии и спросите себя, все ли они действительно полезны и важны? Лишние удалите. Лучше анализировать свои заметки после просмотра кода, постфактум. Пока вы разбираетесь с кодом, пишите сколько угодно комментариев, а потом спокойно просмотрите их и решите, что оставить.
Оставлять комментарии только для того, чтобы подчеркнуть свою правоту, не всегда полезно (или разумно). Иногда лучше держать своё мнение при себе, чтобы сохранить длительные хорошие отношения с человеком. Кэтрин Дэниелс, «Как давать и получать отзывы»
Вы не обязаны находить проблемы в ходе каждого ревью
Если код хорош и может быть влит в кодовую базу без изменений, то всё прекрасно!
Что надо делать при ревью
Ревью можно улучшить. Как именно? Ниже вы прочтёте предложения, собранные в интернете.
Хвалите хороший код
Не жалейте времени на то, чтобы похвалить сильные стороны кода, прежде чем указывать на недостатки и вносить предложения.
Человеческая природа такова, что нам нужно знать о своих успехах, а не только о неудачах. Разработка — это творческий процесс, в который люди вкладывают душу, они часто принимают многое близко к сердцу. Поэтому похвалы для них ещё более важны. Роберт Бог, «Эффективные ревью без боли»
Вы же хотите, чтобы участники команды воспринимали ревью как приятный и полезный опыт, а не как чистое критиканство. Положительные отзывы снижают напряжённость в отношениях и помогают людям лучше реагировать на критику.
Важно писать позитивные комментарии так, чтобы это не выглядело слащаво или фальшиво. Не должно создаваться впечатление, что вы просто стараетесь подсластить пилюлю.
Избегайте сомнительных комплиментов. Фразы вроде «Хорошая работа, но…» (дальше — список изменений, которые вы предлагаете сделать) выглядят наигранными.
Как сделать похвалы более честными?
Сначала — положительные моменты
Сразу задайте настроение, в первую очередь рассказав о том, что вам понравилось. Теперь это легко можно сделать благодаря новым возможностям ревью кода на GitHub, создавая многострочные комментарии и публикуя их скопом (вместо публикации по мере сохранения), а также делая краткое резюме (отображается в начале отзыва) до внесения комментариев:
Избегайте неизбежных обвинений
Спрашивайте, а не говорите. Лучше задавать вопросы, а не делать заявления.
Заявление — это обвинение. Фраза «Здесь ты не соблюдал стандарты» — это обвинение, намеренное или нет. Задайте вопрос: «Почему ты использовал здесь такой подход?» Роберт Бог, «Эффективные ревью без боли»
Если задавать вопросы, то это улучшит общий настрой, восприятие ревью изменится благодаря приглашению к диалогу и обучению, а автор кода с удовольствием объяснит причину или поищет более удачный способ решения.
В идеале в ответ на корректный вопрос автор сам найдёт баг или предложит внести в код улучшения.
Если вы видите какие-то моменты, которые могут быть ошибками, не надо сразу говорить людям, что они неправы. Обычно достаточно спросить: «Что будет, если я передам этому методу ноль?», и человек наверняка сам скажет: «У меня были сомнения, исправлю». Позволить ему самому решить проблему и предложить улучшить код — гораздо лучше, чем давать указание по исправлению несовершенств. Эрик Дитрих, «Используйте ревью кода для казни»
Будьте скромнее
Задавайте вопросы, а не требуйте. Вместо того чтобы сказать автору, какие нужны изменения, задайте ему вопрос о коде или внесите предложение и спросите автора, что он думает по этому поводу. Так вы передаёте мяч на его сторону поля и выказываете уважение его свободе воли, давая автору шанс объяснить своё решение или высказаться, считает ли ваше предложение полезным для кода.
Вместо «Давай назовём эту переменную username, потому что иначе непонятно» лучше перефразировать предложение в виде вопроса: «Может быть, назвать её username? Текущее имя выглядит не слишком понятно для меня, потому что оно также используется в другом контексте в someotherfile.js.». Дэниел Бадер, «7 способов избежать ухудшения отношений при ревью кода»
Когда вы что-то предлагаете, обязательно объясняйте причину, по которой это изменение может улучшить код.
Используйте личные примеры. Покажите автору кода, что не только он совершал такую ошибку. Это отличный способ смягчить критику: «Мне самому это тяжело далось…», «Я делал то же самое».
Не на каждый вопрос нужно отвечать. Примите для себя сразу, что не на каждый ваш вопрос автор кода должен дать ответ. Так вы сможете задавать в своём отзыве вопросы, заставляющие задуматься. На них необязательно отвечать, чтобы влить код в кодовую базу, но зато они подстёгивают мысль разработчика и в долгосрочной перспективе повышают качество его работы.
Не нарушайте правило «Никаких сюрпризов»
Наверняка каждый участник вашей команды раз за разом совершает одни и те же десять ошибок. Причём труднее всего обнаружить пропуски каких-то элементов. Так что чек-лист — самый простой способ избежать наиболее распространённых ошибок и снизить вероятность пропусков. SmartBear, «Лучшие методики ревью кода»
Конечно, чек-лист не может покрыть все возможные случаи. Но в хороший список достаточно включить все требования, которым должен удовлетворять pull request, чтобы быть слитым с кодовой базой. Это полезный инструмент и для кодера, и для рецензента. Чек-лист может помочь улучшить код, сделать его более последовательным, избежать нарушения правил и стандартов. Новым участникам будет очень полезно законспектировать требования к коду, прежде чем отправлять свой первый pull request и проводить первую ревизию.
Пример чек-листа, с которого можно начать:
Стандарты программирования — это общее соглашение, заключаемое между разработчиками. Набор обязательных для всех рекомендаций по написанию качественного и удобного в сопровождении кода. Стандарты — фундамент ревью, потому что во время ревью мы проверяем код на соответствие стандартам. Вместо того чтобы предъявлять к коду требования, не входящие в стандарты, сделайте запрос на их включение в список рекомендаций.
Без доступного всей команде эталонного проекта стандартов разработчики могут даже не понимать, где обнаружатся проблемы при следующем ревью. А это не добавляет эффективности их работе.
Стандарты должны быть исчерпывающими. Можно опираться на стиль форматирования кода PEP 8, но это недостаточно полный стандарт для использования во время ревью.
Анализируйте то, что нужно, а остальным займутся инструменты
Во время ревью практически никогда не должны возникать проблемы с форматированием кода. Ревизии должны провоцировать появление продуктивных мыслей и дискуссий, а траты времени на стиль и форматирование в этом не помогут. Для подобных вещей используйте инструменты, например линтеры и средства автоматического форматирования.
Заключение
Это статья о том, как давать положительные заключения и правильно критиковать, как успешно вносить предложения во время ревью кода. Я предлагаю вам сделать сжатую версию этого руководства с выделенными ключевыми моментами и раздать её каждому участнику команды. Положите инструкцию в общий репозиторий, чтобы любой мог начать её разбор и предложить свои изменения, и тогда вся команда будет вовлечена в обсуждение.
Также рекомендую подумать о том, как у вас создаётся код, который потом попадает на ревью. Вероятно, вы хотите, чтобы кодер и рецензент имели похожие представления о техническом дизайне до того, как код окажется на ревью. Заранее решите, кто будет писать код для конкретной фичи, а кто будет рецензировать, и поощряйте их работать вместе, чтобы эти двое обсуждали структуру кода и его промежуточные варианты, прежде чем проверять финальную версию. Нам же нужна качественная архитектура (две головы лучше), но также нужно избегать излишних дебатов во время анализа, когда оба разработчика предлагают совершенно разные решения (одному из них придётся полностью переписать уже готовый код).
Если ещё до ревью между автором и рецензентом установится крепкое сотрудничество, то во время ревью, скорее всего, всплывёт лишь несколько мелких проблем.