Перевод статьи «A zen manifesto for effective code reviews».
Когда вы пишете код, любые отвлекающие факторы ужасно раздражают. Вы в «зоне», парите где-то высоко. И вдруг… митинг, стендап <вставить-нужное>… Ну просто прекрасно!
В этом контексте ревью кода может восприниматься как еще одна помеха продуктивности. И, честно говоря, я могу это понять.
Ревью кода это трудоемкий процесс
Вам нужно не только прервать свою работу, но и погрузиться в чужой код. Много энергии уходит просто на смену фокуса.
Ревью кода это затратное по времени занятие
Согласно опроса Slack Overflow 2019, 56,4% разработчиков проводят по четыре часа в неделю (или даже больше) за проверкой чужого кода. Время, которое тратится на ревью кода, может составлять до 20% рабочей недели разработчика!
Ревью кода может раздражать
Если речь идет о проверке вашего кода, вас может раздражать как отказ по вашему пул-реквесту, так и необходимость ожидать ревью несколько часов, если не дней. А ревьюер может считать необходимость разбираться в чьем-то коде досадной помехой для своего продуктивного рабочего дня.
Да, ревью кода это порой отнимающий время и силы труд, не вызывающий при этом приятных эмоций.
Но это также хороший способ делиться знаниями, предотвращать появление багов и, среди прочего, укреплять культуру компании.
Далее следует манифест для авторов кода и ревьюеров, который призван привнести умиротворенность в ревью кода.
Манифест автора кода
Хотите, чтобы ваш пул-реквест был принят без лишних задержек? Вот что вы (как автор кода) можете предпринять.
Отправляйте свой код, когда он полностью закончен
Звучит, как очевидная истина. Но дело в том, что в большинстве случаев, если машина не работает, это не значит, что она сломана: это значит, что ее просто не включили!
Мельчайшие детали могут оказать большое влияние на то, как будет воспринята ваша работа. И вам совершенно не нужно, чтобы ваши коллеги подумали, будто они тратят время на проверку недописанного кода.
Я: Там просто </div> пропущен!
Вы: Да, я знаю, но из-за этого не работал весь код, и мне пришлось потратить 20 минут на выяснение, в чем дело.
Итак, вот что вы можете сделать:
- Протестировать свой код самостоятельно. Добавить в название или ярлык «WIP» («Work in process»), если работа еще не закончена.
- Сделать ревью своего кода самостоятельно. Используйте функцию diff вашего редактора кода или инструмент проверки версий, чтобы отловить возможные ошибки.
- Прежде чем обращаться к ревьюеру, убедитесь, что ваши интеграционные тесты зеленые, – это сэкономит время вашего коллеги.
Делайте маленькие пул-реквесты
Я понимаю, у вас большая, важная и сложная фича, и в связи с этим у вас сильное желание отправить длинный пул-реквест. Но в большинстве случаев лучше отправлять маленькие.
Ревью кода отнимают силы. А крупномасштабные ревью отнимают много сил.
Будьте добрее к коллегам и разделите свой пул-реквест на маленькие кусочки. Таким образом вы и о себе позаботитесь:
- Вы получите более качественный фидбэк. Чем длиннее пул-реквесты, тем ниже качество обратной связи в пересчете на строку кода. Подавайте маленькие (но не слишком) пул-реквесты, и вы увеличите свои шансы получить отличный фидбэк.
- Ревьюеры будут быстрее одобрять ваши пул-реквесты. Это ситуация win-win.
500 строк кода = «выглядит отлично».
Ревью кода.
Для зануд привожу исследование, проведенное командой Cisco. Результаты показывают, что после просмотра 400 строк кода способность найти в нем недостатки стремительно падает.
Следующий принцип поможет вам держать размер своих пул-реквестов под контролем.
Ограничивайте масштаб
Ваш пул-реквест должен иметь простую, уникальную и совершенно определенную область действия. Это может быть определенный функционал, user-story или исправление бага.
Представьте, что внимание вашего ревьюера измеряется очень ограниченным количеством «очков». Каждый раз, когда он фокусируется на чем-то, он использует 1 очко. Что будет, когда у него не останется очков в запасе?
LGTM 👍
Делайте все возможное, чтобы снизить «шум» вокруг вашей работы. Помните о концентрации внимания ревьюера. Например, избегайте бессмысленных изменений (например, пропуска строк). Они не добавляют никакой ценности и усложняют проверку кода.
Если ваш пул-реквест касается изменений в поведении программы, не включайте в него изменения, касающиеся форматирования. И наоборот, если ваш пул-реквест это изменения в форматировании, не включайте в него еще и изменения, касающиеся поведения. Ревьюер может просто не обратить на них внимания.
Давайте контекст
Относитесь к своему пул-реквесту как к документации для новичков. Давайте читателю какой-то контекст.
Начните с поясняющего названия.
Затем напишите понятное объяснение того, что вы делаете и почему вы это делаете. Каково назначение этого пул-реквеста? Почему эти изменения необходимы? Как вы подошли к этой проблеме?
Взято из репозитория react
Описание также является подходящим местом, чтобы указать на нерешенные проблемы и открытые вопросы. Ревьюер может дать вам совет и разблокировать таким образом вашу дальнейшую работу.
Вы работаете над какой-то видимой частью продукта? Скриншоты помогут донести вашу мысль быстрее.
- Покажите разницу в стиле «было – стало».
- Используйте цветные стрелки.
- При желании добавьте запись экрана.
Наконец, оставляйте в коде информационные сообщения, чтобы дать ревьюеру понять причины ваших действий.
Поддерживайте чистоту в истории коммитов, чтобы читателю было легче идти по вашим следам. Используйте комментарии, чтобы указать на исследованные вами альтернативы.
Приветствуйте любую обратную связь
Отказы ранят. А когда отвергают ваш код, это ранит даже еще сильнее.
Но это нормально. Просто не нужно воспринимать их как нечто личное.
Комментарии и предложения это возможность учиться и становиться лучшим разработчиком, чем вы были до этого.
Манифест ревьюера
А теперь давайте рассмотрим несколько принципов, которые могут помочь вам стать лучшим ревьюером.
Правильные установки
Когда ревьюер не желает делиться своими знаниями или, наоборот, ведет себя чрезмерно покровительственно, это ни при каких условиях не идет на пользу команде. Просто будьте добрее к людям. Точка.
Хотите сделать ревью кода более интересным для себя? Поищите что-нибудь, чему вы можете научиться по ходу дела. Новая библиотека, новый метод, новая концепция, более простой способ что-то сделать. Что полезного вы можете извлечь из этого кода?
Если вы более опытный разработчик, чем автор кода, подумайте, какими знаниями вы могли бы с ним поделиться. Как вы можете использовать это ревью для передачи своего опыта? Как вы можете помочь человеку стать лучшим разработчиком, чем он есть?
Как проводить ревью кода
Что проверять
На что я должен смотреть? Без четкого понимания, на что стоит обращать внимание, легко потеряться. Вот что можно сделать.
Для начала, проверьте, выполняет ли код свое предназначение. Есть ли в новом коде какие-то непонятные вам части? Легко ли код тестируется? Протестируйте его. Не проверив все, указанное здесь, нет смысла двигаться дальше.
Теперь, когда мы знаем, что код работает, время сосредоточиться на его реализации.
Подумайте, как бы вы подошли к решению данной проблемы. Сделали ли бы что-то другим способом? Есть ли здесь возможности для рефакторинга или абстрагирования? Нет ли здесь изобретения велосипеда? Используются ли в этом коде стандартные шаблоны проектирования?
Что не нужно проверять
Если код можно улучшить, это еще не значит, что его непременно нужно улучшить.
В конечном итоге, ревью кода это компромисс между качеством и скоростью. Если принимать во внимание масштаб и стадию разработки, возможно, имеет смысл пропустить какие-то вещи.
Также не стоит заниматься вещами, которые можно автоматизировать. Доверьте своему линтеру вылавливать пропущенные точки с запятой и лишние отступы. Бесконечные дебаты о пробелах и табах тоже совершенно бессмысленны.
Наконец, не увеличивайте масштаб пул-реквеста. Если вы думаете, что нужно сделать что-то еще, создайте для этого новый пул-реквест или задачу.
Делайте ревью своевременно
Есть как минимум три хорошие причины, по которым сроки ревью должны измеряться в часах, а не в днях:
- автор кода может быстрее перейти к новой задаче,
- снижается стоимость переключения между контекстами,
- уменьшается риск конфликтов слияния между ветками.
Как давать фидбэк по результатам ревью?
В том что касается обратной связи форма имеет не меньшее значение, чем содержание.
Вы знаете, что при письменном общении нейтральный контент кажется более негативным, чем он есть на самом деле? Помните об этом и при необходимости вставляйте в текст эмодзи, чтобы точнее передать тон вашего комментария.
Также, даже если вы абсолютно уверены, что есть лучший способ что-то сделать, чаще всего лучше задать вопрос, чем предложить изменение. Плюс, вопросы воспринимаются менее агрессивно.
Наконец, хвалите людей, когда они что-то сделали хорошо. Ревью кода это, помимо всего прочего, прекрасная возможность воздать должное коллегам за хорошо проделанную работу. Будьте креативны и изобретательны:)
