5 рекомендаций по оптимизации пул-реквестов

Создание пул-реквеста (запроса на размещение изменений в основной ветке) и ожидание результатов ревью  —  стандартные процедуры в процессе написания кода, являющиеся важной и неотъемлемой частью ежедневных будней разработчика. Они предназначены для следующих целей.

  1. Обмен информацией о базе кода. 
  2. Наставничество над разработчиками для обеспечения их профессионального роста. 
  3. Поддержание стандартов высокого качества. 

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

JavaMentor
JavaMentor

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

1. Подбирайте информативное имя 

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

Например, такое имя пул-реквеста, как “BUGFIX” (“Исправление ошибки”), укажет рецензенту на необходимость проверить факт исправления ошибки. Но где именно? И какой ошибки?  

Лучше сформулировать так  —  “[FIX] Обновление списка продуктов при поступлении новых продуктов из фонового потока”. Такое имя сразу же сообщает рецензенту следующую информацию.

  1. Речь идет об исправлении ошибки, а не о реализации функциональности, тестах и т. д.). 
  2. Недочет связан со списком продуктов приложения. 
  3. Указан момент совершения ошибки. 
  4. Содержит желаемый результат. 

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

2. Уделяйте внимание описанию 

Иногда пул-реквест сопровождается емким именем, но бессодержательным (или даже дублирующим имя) описанием.

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

При его составлении попробуйте ответить на 5 вопросов: Для чего? Где? Кто? Что? Когда? Таким образом вы объясните: 

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

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

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

Если пул-реквест связан с UI, то почему бы не предоставить снимки состояний (snapshot) результата или даже небольшую GIF-анимацию. 

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

3. Поддерживайте компактность и семантическую однородность пул-реквестов 

Нет ничего печальнее на свете, чем проверять пул-реквест длиной в несколько тысяч строк. 

Никуда не годится!

Подобные показатели повергнут рецензента в ужас: так много всего  —  неудивительно, если он что-нибудь упустит из виду. Кроме того, данный пул-реквест семантически разнородный. Он может содержать исправление ошибки, рефакторинг, тесты и многое другое. 

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

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

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

  • Правильно ли выполнена реализация компонента? 
  • Покрывают ли тесты все ключевые и связанные с ними пограничные случаи? 
  • Является ли API компонента содержательным и эргономичным? 

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

4. Обновляйте документацию 

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

Если мы задействуем новые API, то не обойтись без обновления README.md. В целом для отслеживания всех изменений в базе кода нужен CHANGELOG.md. А это еще одна часть документации, подлежащая актуализации. 

Уделяя внимание этому важному аспекту при подготовке пул-реквеста, мы достигаем 2 цели: 

  1. обновляем документацию; 
  2. экономим время рецензента, избавляя его от необходимости писать такой комментарий, как “не забыть обновить CHANGELOG.md”. 

5. Не допускайте опечаток 

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

Кроме того, рецензент должен их отмечать, затрачивая время на составление к ним комментария. 

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

  1. Проверяйте внесенные в код изменения более одного раза перед тем, как нажать кнопку “Create Pull Request” (“Создать пул-реквест”). При соблюдении совета #3 это не займет много времени, поскольку пул-реквест будет небольшим. 
  2. Подключите средство проверки грамматики в Xcode. Для этого откройте данную среду разработки, кликните “Edit” (“Редактирование”) на панели инструментов, выберите сначала “Format” (“Форматирование текста”), затем “Spelling and Grammar” (“Правописание и грамматика”) и в завершении кликните “Check Spelling While Typing” (“Проверка правописания в процессе набора текста”). 

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

Заключение 

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

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

Читайте также:

Читайте нас в Telegram, VK и Яндекс.Дзен


Перевод статьи Riccardo Cipolleschi: 5 Tips To Create Better Pull Requests

Предыдущая статья12 ошибок начинающих веб-разработчиков
Следующая статьяПять парадоксов с вероятностью, которые вас озадачат