Пулл-реквесты с эмпатией

https://slack.engineering/on-empathy-pull-requests-979e4257d158
  • Перевод


В компании Slack считают, что эмпатия — это суперспособность, и у разработчиков она должна быть включена по максимуму.

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

Хорошая культура код ревью основана на эмпатии к вашим коллегам-разработчикам. Что мы имеем в виду, когда говорим об эмпатии? Brené Brown, техасский профессор и исследователь психологии, предлагает подходящее определение. По ее мнению, эмпатия включает в себя четыре компонента:

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

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

Эмпатия на практике — пулл-реквесты



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

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

Хорошие пулл-реквесты предоставляют контекст задачи


Первое и наиболее важное: хорошие пулл-реквесты предоставляют контекст для проверяющего код. Обычно, когда вы создаете пулл-реквест:

  • Вы довольны своей работой! Вы исправили баг или разработали новую фичу. Круто!
  • Весь код уже присутствует в вашей голове: вы знаете, как всё работало изначально, и понимаете, что поменяли в процессе.
  • Вы готовы приступить к другим задачам.

С другой стороны:

  • Коллега, который проверяет ваш код, не участвовал в исправлении бага.
  • У него нет понимания, чем именно вы занимались.
  • У него нет идей по поводу того, с какими проблемами вы встретились в процессе написания кода.

По сути, ваш ревьюер совсем не берёт в расчёт контекст задачи. Ваш пулл-реквест должен предоставить ему этот контекст. И есть несколько способов сделать это:

  • Дайте пулл-реквесту подходящий заголовок, чтобы люди понимали, что им предстоит проверять перед тем, как они начнут.
  • Дайте развернутое описание, чтоб сообщить ревьюеру, как вы пришли к такому решению. Что вы попробовали, что из этого не сработало? Почему именно выбранное решение — правильное?
  • Обязательно дайте ссылки на любые другие материалы, которые могут прояснить ситуацию — ссылка на тикет в багтрекере или на Slack-архив могут заметно помочь в описании проблемы.
  • Спрашивайте мнение проверяющего. Например, если вам любопытно, можно ли было избежать вызова к «fooBarFrobber», спросите об этом явно — так вы сможете направить взгляд ревьюера именно на это место.
  • Наконец, вы должны объяснить проверяющему ваш код, что происходит в целом. Что вы исправили? Возникли ли проблемы при исправлении бага? Какие еще были способы пофиксить его, и почему вы решили исправить ошибку именно так?

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

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

Хороший пулл-реквест должен быть сфокусированным


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

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

Хорошие пулл-реквесты добавляют уверенности в коде


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

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

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

Заключение


Хороший пулл-реквест — это проявление эмпатии, как для автора, так и для проверяющего.

Если вы — автор, добавление детальной информации о решаемой проблеме в ваш пулл-реквест позволит не только улучшить качество проверки, но и вызвать благосклонность ревьюера. Хорошие пулл-реквесты, которые сфокусированы на одной проблеме, снабжены тестами и комментариями, позволяют забыть контекст, не опасаясь за этот участок кода в будущем. Если вы — проверяющий, хорошо сформированные пулл-реквесты сделают вашу работу более эффективной, и направят внимание на ревью кода, а не на уточнение деталей в контексте задачи. Как итог, от качественных пулл-реквестов выигрывают абсолютно все.
  • +11
  • 4,3k
  • 8
MobileUp 55,55
Мобильная разработка повышенной сложности
Поделиться публикацией
Комментарии 8
  • 0
    По хорошему, вся эта информация может быть сразу в тексе коммита.
    • 0
      Соглашусь, каждый коммит должен сопровождаться содержательным сообщением, а не чем-то вроде «fix». Но не стоит пренебрегать описанием при создании пулл-реквеста, где можно добавить дополнительной информации о решаемой проблеме. Это особенно полезно, если команда — распределенная, и ревьюер не может «дойти ногами» до автора реквеста и задать ему какие-то уточняющие вопросы.
      • 0
        На мой взгляд, зависит от флоу.
        Если в реквесте коммитов несколько (много), то удобно, когда есть краткое содержание в описании.
        Если же один реквест ~= один коммит, и в нём всё подробно описано, то да, в реквесте можно практически ничего не писать.
      • +1

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

      • 0
        Pair programming, mob programming уже непопулярны в слак?) Зачем я буду включать коллегу в ревьюеры если он не в курсе, что я делаю. Значит изначально работа велась неверно.
        • 0

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


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

          • +1

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

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

        Самое читаемое