Это вызовет улыбку на лице каждого рецензента.

Основываясь на своем опыте проведения большого количества обзоров кода, я резюмирую моменты, которые «этот вид запроса на проверку (запрос на слияние GitLab, запрос на слияние GitHub) полезен». Мой скрытый мотив заключается в том, что когда участники, с которыми я работаю, меняются, я хочу, чтобы документ суммировал мои мысли как рецензента.

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

1. Соответствовать критериям проверки

Кажется, меня упрекнут, если это не связано со стилем написания, но им часто пренебрегают, так что я его перепроверю. Запрос на проверку — это передача задачи от рецензента рецензенту. Я думаю, что условия отправки на рецензию определяются для каждой команды, но если предварительные условия не будут выполнены в первую очередь, это вызовет переделку в истории перед написанием, поэтому, пожалуйста, не тратьте время друг друга. Будь осторожен. Общее правило заключается в следующем:

Назначить уполномоченного

Назначьте рецензентов, чтобы было понятно, у кого мяч с заданием. Даже если команда не выберет рецензентов заранее, рецензенты будут назначены в назначенное время. Особенно легко забыть при повторном просмотре после отправки обратно.

Удалить незавершенное производство

Чтобы предотвратить случайное слияние, GitLab может пометить незавершенный (незавершенный) мерж-реквест как свой WIP. Будьте внимательны и не забудьте удалить WIP, потому что мы хотим, чтобы вы объединили его при отправке на проверку.

Пройти проверку подлинности

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

2. Сообщайте необходимую и достаточную информацию

Запрос на проверку — это не документ, который нужно прочитать, а краткое изложение информации. Не будь слишком длинным или слишком коротким. Сосредоточьтесь на информации, которая нужна рецензенту, или, точнее, только на той информации, которая ему нужна. Мне не нужен парень, который говорит: «Извините, что беспокою вас, но, пожалуйста, дайте мне отзыв».

Название

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

Контент

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

В GitLab/GitHub есть функция регистрации шаблонов для написания Merge Requests/Pull Requests. Вам следует использовать шаблон, если ваш проект имеет фиксированный формат или вы часто забываете написать необходимую информацию.

3. Воспользуйтесь снимками экрана

Как говорится, «картинка стоит тысячи слов». Не пытайтесь объяснить только текстом, а активно используйте снимки экрана. Это особенно полезно для модификаций, которые изменяют пользовательский интерфейс. Есть несколько причин, по которым

  • Рецензент должен иметь возможность просмотреть экран сначала как внешнюю спецификацию, прежде чем код.
  • Я не создавал рецензента сам, поэтому наличие экрана облегчает заполнение пробелов в знаниях между рецензентом и рецензентом.

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

4. Используйте маркеры и контрольные списки

Вместо того, чтобы составлять предложения в своем стиле с использованием таких символов, как разрывы строк, двухбайтовые пробелы и символы, такие как ■ □ ○, используйте Markdown для составления предложений. Вместо того, чтобы объяснять длинными предложениями, активно используйте маркеры, чтобы сделать объяснение более понятным и понятным.

Точки списка

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

Пронумерованные маркеры

При описании ряда операций, таких как процедура воспроизведения или процедура проверки работы, нумерация их цифрой 1 облегчает понимание порядка с первого взгляда. Если вы установите 1. начиная со второй строки, она будет автоматически пронумерована.

Контрольный список

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

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

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

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

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

6. Упростите задачу для своей команды

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

Сводка

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

Дополнительные материалы на PlainEnglish.io.

Подпишитесь на нашу бесплатную еженедельную рассылку новостей. Подпишитесь на нас в Twitter, LinkedIn, YouTube и Discord .