В этой статье мы исследуем эффективные практики для разработчика, отправляющего свой код на ревью. Эти практики не только упростят жизнь ревьюеру, но и помогут извлечь максимальную пользу из этого опыта и значительно сократят time-to-market.

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

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

В моей статье я собрала наиболее эффективные практики, которые по опыту помогают ускорить и упростить процесс код-ревью. Однако, решение о том, какие именно из этих практик использовать, всегда должно приниматься вместе с командой и в зависимости от задачи, которая отправляется на ревью. Например, если задача для код-ревью является небольшой (исправление мелкого бага), нет смысла тратить время на подготовку детального описания проблемы и способов её решения. Важно поддерживать баланс, чтобы обеспечить наиболее быстрое и эффективное ревью кода.

Как подготовить код к ревью

1. Перед отправкой кода на ревью обязательно проведите все автоматические проверки (тесты, линтеры и т.д.)

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

2. Мердж Реквест (МР) должен быть небольшим, последовательным и завершенным

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

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

Если какой-то из МРов не пройдет ревью, у вас будет часть задачи, которую можно задеплоить и закрыть, а на правки и повторное ревью пойдет только незаконченная часть крупной задачи.

3. Включайте в ваш запрос на ревью всю необходимую информацию

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

  • Ссылку на открытый пулл или мердж реквест в гитлаб/гитхаб;

  • Ссылку на задачу;

  • Описание проблемы, которую решаете

    • Какой запрос от бизнеса;

    • Если это фикс бага - пошаговое описание, как и когда возникает баг;

  • Ссылку на документацию по задаче (если есть)

    • Апи доки;

    • Документация с описанием сервиса;

    • Архитектурные схемы;

  • Краткое описание текущего реализованного решения;

  • Будет отлично предоставить варианты решений, которые вы рассматривали, с подробным описанием плюсов и минусов каждого подхода

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

  • Выделите те моменты, где у вас возникают сомнения или требуется особое внимание ревьюера (например, критические изменения);

  • В случае внесения изменений во фронтенд, прикрепите скриншоты с новым функционалом или сравнительные изображения 'как было' и 'как стало';

  • Обновленные зависимости

    • Если ваше изменение влияет на зависимости проекта, укажите обновления и их причины;

  • и т.д.

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

4. Просмотрите изменения перед тем как отдавать его на ревью

  • Убедитесь, что текущие изменения решают поставленную задачу;

  • Обратите внимание на обработку краевых случаев и ошибок;

  • Удостоверьтесь, что все необходимые данные при ошибках корректно логгируются (параметры, использованные при вызове функции, информация об ошибке, стек вызовов и прочая полезная информация);

  • Проверьте, отсутствует ли дублирование кода и не существует ли в текущем проекте утилит, которые реализуют функционал, реализованный вами в текущем изменении;

  • Убедитесь, что комментарии к коду понятны и необходимы. Они должны объяснять, почему код написан именно так, а не описывать, что код делает.

Это лишь несколько примеров критериев, которые стоит проверить перед отправкой на ревью. Вы можете создать более полный чеклист для вашей команды или воспользоваться уже существующими, например https://github.com/mgreiler/code-review-checklist.

После ревью

1. Хорошим тоном считается обработать каждый комментарий

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

2. Исправьте все повторяющиеся проблемы в МР

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

3. Разберите каждый комментарий

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

4. Ведите список полезных замечаний и предложений по ревью вашего кода

Это позволяет вам систематически обрабатывать комментарии и периодически возвращаться к ним для переосмысления.

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

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

Эмоциональная Атмосфера в ходе код-ревью

1. Будьте готовы к обратной связи

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

2. Обсуждайте комментарии

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

3. Если комментарии токсичные, проявите вежливость

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

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

4. Если комментарий холиварный, лучше вынести его обсуждение за рамки ревью

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

5. Поблагодарите ревьюера

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

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

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