В этой статье мы исследуем эффективные практики для разработчика, отправляющего свой код на ревью. Эти практики не только упростят жизнь ревьюеру, но и помогут извлечь максимальную пользу из этого опыта и значительно сократят time-to-market.
Мы не будем углубляться в важность код-ревью для команды и проекта. Сосредоточимся на практиках для разработчика, проходящего код-ревью.
В первую очередь, нужно понимать, что код ревью - это обратная связь о проделанной работе. Не стоит комментарии ревьюера воспринимать негативно, близко к сердцу или отчаиваться, если комментариев к коду много. Цель ревьюера - выявить области для улучшений, обсудить код и подход к решению, а не критиковать личность разработчика. Наоборот, стоит поблагодарить за обратную связь, каждый комментарий - ваша возможность вырасти профессионально и впитать ценный опыт коллег.
В моей статье я собрала наиболее эффективные практики, которые по опыту помогают ускорить и упростить процесс код-ревью. Однако, решение о том, какие именно из этих практик использовать, всегда должно приниматься вместе с командой и в зависимости от задачи, которая отправляется на ревью. Например, если задача для код-ревью является небольшой (исправление мелкого бага), нет смысла тратить время на подготовку детального описания проблемы и способов её решения. Важно поддерживать баланс, чтобы обеспечить наиболее быстрое и эффективное ревью кода.
Как подготовить код к ревью
1. Перед отправкой кода на ревью обязательно проведите все автоматические проверки (тесты, линтеры и т.д.)
Автоматические проверки обеспечивают мгновенный фидбек и упрощают процесс исправления ошибок. Кроме того, они позволяют ревьюеру сосредотачиваться на более значимых аспектах кода, не тратя время на элементарные проверки кодовой базы. Также удостоверьтесь, что ваш код соответствует стайл-гайдам вашей команды, особенно если эта проверка не автоматизирована.
2. Мердж Реквест (МР) должен быть небольшим, последовательным и завершенным
Разбивайте крупные задачи на несколько логических подзадач. В небольших изменениях проще ориентироваться и выявлять проблемы, меньше вероятности упустить баг. Небольшой МР ревьюер может просмотреть, не теряя концентрации и контекста. Его легче деплоить, тестить и откатывать при необходимости. Ревьюер потратит в разы меньше времени на ревью даже крупной задачи, разделенной на мелкие подзадачи. Разбивая большие задачи на меньшие, вы создаете более управляемые итерации разработки, что упрощает код-ревью и обеспечивает более плавное внедрение изменений.
МР должен быть завершенный, его деплой не должен ломать логику сервиса, в нем должны быть изменения кода, тесты и документация по этим изменениям.
Если какой-то из МРов не пройдет ревью, у вас будет часть задачи, которую можно задеплоить и закрыть, а на правки и повторное ревью пойдет только незаконченная часть крупной задачи.
3. Включайте в ваш запрос на ревью всю необходимую информацию
Помните, что у ревьюера есть свои задачи, и переключение контекста для разработчика стоит дорого. Вы значительно сэкономите время и силы, как свои, так и ревьюера, если приложите в запрос на ревью всю необходимую информацию:
Ссылку на открытый пулл или мердж реквест в гитлаб/гитхаб;
Ссылку на задачу;
Описание проблемы, которую решаете
Какой запрос от бизнеса;
Если это фикс бага - пошаговое описание, как и когда возникает баг;
Ссылку на документацию по задаче (если есть)
Апи доки;
Документация с описанием сервиса;
Архитектурные схемы;
Краткое описание текущего реализованного решения;
Будет отлично предоставить варианты решений, которые вы рассматривали, с подробным описанием плюсов и минусов каждого подхода
Описание различных подходов к решению задачи может быть удобно представлено в виде майнд-карты, которую также можно приложить для ознакомления ревьюера;
Выделите те моменты, где у вас возникают сомнения или требуется особое внимание ревьюера (например, критические изменения);
В случае внесения изменений во фронтенд, прикрепите скриншоты с новым функционалом или сравнительные изображения 'как было' и 'как стало';
Обновленные зависимости
Если ваше изменение влияет на зависимости проекта, укажите обновления и их причины;
и т.д.
Если быть кратким - прикладывайте всю информацию, которая будет полезна для ревьюера, чтобы погрузиться в контекст. Это поможет избежать лишних вопросов и уточнений от ревьюера, сократит время процесса и, как следствие, ускорит внедрение изменений в продукт и снизит итоговые затраты на разработку фичи.
4. Просмотрите изменения перед тем как отдавать его на ревью
Убедитесь, что текущие изменения решают поставленную задачу;
Обратите внимание на обработку краевых случаев и ошибок;
Удостоверьтесь, что все необходимые данные при ошибках корректно логгируются (параметры, использованные при вызове функции, информация об ошибке, стек вызовов и прочая полезная информация);
Проверьте, отсутствует ли дублирование кода и не существует ли в текущем проекте утилит, которые реализуют функционал, реализованный вами в текущем изменении;
Убедитесь, что комментарии к коду понятны и необходимы. Они должны объяснять, почему код написан именно так, а не описывать, что код делает.
Это лишь несколько примеров критериев, которые стоит проверить перед отправкой на ревью. Вы можете создать более полный чеклист для вашей команды или воспользоваться уже существующими, например https://github.com/mgreiler/code-review-checklist.
После ревью
1. Хорошим тоном считается обработать каждый комментарий
Важно внести изменения в код в соответствии с предложениями ревьюера или объяснить, почему вы предпочли оставить текущую реализацию. В случае неполного понимания комментария или неясности причины предложенного улучшения, не стесняйтесь задавать уточняющие вопросы.
2. Исправьте все повторяющиеся проблемы в МР
Проверьте, чтобы в остальных частях изменений не встречались повторяющиеся проблемы, указанные в комментарии. В МР часто возникают аналогичные ошибки, поэтому важно убедиться, что все подобные проблемы были устранены.
3. Разберите каждый комментарий
Глубокое понимание каждого замечания поможет профессионально расти с каждым код-ревью. Работая над улучшением кода в соответствии с комментариями и задавая уточняющие вопросы, вы активно развиваетесь в своей профессиональной области.
4. Ведите список полезных замечаний и предложений по ревью вашего кода
Это позволяет вам систематически обрабатывать комментарии и периодически возвращаться к ним для переосмысления.
Ревьюер часто дает ценные и полезные комментарии, которые касаются не только текущего кода, но и предостерегают от возможных проблем в будущем. Хотя некоторые из этих замечаний могут не требовать срочного исправления, они представляют собой ценный опыт и знание вашего ревьюера. Старайтесь активно воспринимать и использовать этот опыт.
Составление такого списка поможет предотвратить повторение ошибок. В моей практике я часто сталкиваюсь с ситуациями, когда разработчики повторяют ошибки, которые исправляли после ревью в предыдущих задачах. Составление списка с комментариями, по которым разработчик может пройти, помогает избежать этих повторений и обеспечивает более качественный код в будущем. Однако в список выносить стоит только существенные и важные комментарии, которые пригодятся вам в будущей работе.
Эмоциональная Атмосфера в ходе код-ревью
1. Будьте готовы к обратной связи
У ревьюера такие же цели, как и у вас: внедрение вашей фичи в продакшн при сохранении высокого уровня кода. Ревьюер не стремится обидеть или задеть вас. Следует воспринимать комментарии ревьюера как ценный опыт, способствующий вашему профессиональному росту.
2. Обсуждайте комментарии
Если возникают вопросы по комментариям, обсудите их с ревьюером. Важно понимать подход и мнение друг друга для наилучшего результата.
3. Если комментарии токсичные, проявите вежливость
Часто невежливость в комментариях может быть следствием плохо продуманных замечаний, и важно не воспринимать их близко к сердцу, а вникнуть в суть.
В случае недопонимания, если вы явно видите грубость или токсичность - лучше обратиться к человеку напрямую или к вашему менеджеру. Будьте вежливы и спокойны. Важно избегать грубых ответов на комментарии, так как это только усугубит ситуацию.
4. Если комментарий холиварный, лучше вынести его обсуждение за рамки ревью
Написание кода - творческий процесс, и у каждого индивидуальное представление о "красоте" кода. Однако, в командной работе важно придерживаться стандартов, установленных командой. Идеально, чтобы стиль кода был единым, не выделяя конкретного автора. Если обсуждение изменения начинает принимать характер холивара, а комментарий не улучшает изменение на ваш взгляд, лучше вынести этот вопрос для обсуждения отдельно или обратиться к менеджеру, чтобы не затягивать процесс код-ревью. Но зачастую лучше согласиться с ревьюером и внести изменения, в этом случае код в проекте скорее всего будет более консистентным.
5. Поблагодарите ревьюера
Поблагодарите ревьюера за проделанную работу, за комментарии и предложения, оставленные вам во время ревью. Это улучшит атмосферу в команде и поспособствует продуктивному сотрудничеству.
В заключение можно отметить, что качественная подготовка кода к ревью существенно облегчит жизнь ревьюера, ускорит процесс проверки и сократит число итераций ревью, способствуя более быстрому внедрению изменений.
Код-ревью является мощным инструментом не только для повышения качества кода, но и для профессионального развития разработчиков. Систематическая обработка комментариев, создание списков полезных замечаний и предложений, а также активное взаимодействие с ревьюером содействуют созданию более качественного и стабильного кода и профессиональному развитию каждого участника команды разработки.
