Источник: Nuances of Programming
Создание пул-реквеста (запроса на размещение изменений в основной ветке) и ожидание результатов ревью — стандартные процедуры в процессе написания кода, являющиеся важной и неотъемлемой частью ежедневных будней разработчика. Они предназначены для следующих целей.
- Обмен информацией о базе кода.
- Наставничество над разработчиками для обеспечения их профессионального роста.
- Поддержание стандартов высокого качества.
Как правило, процесс разбивается на 2 этапа: один разработчик готовит пул-реквест, а другой (или несколько) проводит ревью, отмечая удавшиеся участки кода и фрагменты, требующие доработки.
В этой статье мы остановимся на первом этапе, акцентируя внимание на том, как создать добротный пул-реквест и тем самым облегчить коллегам процесс его проверки. Упрощая им работу, мы повышаем продуктивность самого ревью. К тому же не будет лишним составить о себе мнение как о профессионале и заработать в глазах рецензентов дополнительные бонусы.
1. Подбирайте информативное имя
Прежде всего всегда следует помнить о том, что в отличие от нас рецензенты не знают контекст. Вот почему информативное имя сразу же подскажет им, что нужно проверять, и введет их в курс дела.
Например, такое имя пул-реквеста, как “BUGFIX” (“Исправление ошибки”), укажет рецензенту на необходимость проверить факт исправления ошибки. Но где именно? И какой ошибки?
Лучше сформулировать так — “[FIX] Обновление списка продуктов при поступлении новых продуктов из фонового потока”. Такое имя сразу же сообщает рецензенту следующую информацию.
- Речь идет об исправлении ошибки, а не о реализации функциональности, тестах и т. д.).
- Недочет связан со списком продуктов приложения.
- Указан момент совершения ошибки.
- Содержит желаемый результат.
Совет: в зависимости от политики компании, внутрикомандных правил или других соглашений иногда бывает полезно добавлять перед именем эмоджи. Например, мы часто используем 🐛, обозначающий исправление ошибок, или 📚 , указывающий на документы. Такие идеограммы дают визуальное представление о содержании.
2. Уделяйте внимание описанию
Иногда пул-реквест сопровождается емким именем, но бессодержательным (или даже дублирующим имя) описанием.
А ведь оно играет важную роль, предоставляя рецензенту всю необходимую дополнительную информацию. Именно здесь разработчик обосновывает все принятые им решения в процессе написания кода.
При его составлении попробуйте ответить на 5 вопросов: Для чего? Где? Кто? Что? Когда? Таким образом вы объясните:
- для чего нужен пул-реквест;
- все предположения и намерения, лежащие в его основе;
- преимущества/недостатки выбранного решения;
- планируется ли дальнейшая проработка каких-либо участков кода.
Попробуйте подключить дополнительные ресурсы. Если пул-реквест представляет из себя исправление ошибки, то целесообразно сопроводить его ссылкой на соответствующую проблему, а в случае реализации функциональности — на связанную с ней задачу.
Если он нацелен на повышение производительности, то можно добавить графики с показателями до и после его осуществления.
Если пул-реквест связан с UI, то почему бы не предоставить снимки состояний (snapshot) результата или даже небольшую GIF-анимацию.
Подобного рода информация помогает рецензенту проводить ревью, сосредотачиваясь на нужных частях пул-реквеста.
3. Поддерживайте компактность и семантическую однородность пул-реквестов
Нет ничего печальнее на свете, чем проверять пул-реквест длиной в несколько тысяч строк.
Подобные показатели повергнут рецензента в ужас: так много всего — неудивительно, если он что-нибудь упустит из виду. Кроме того, данный пул-реквест семантически разнородный. Он может содержать исправление ошибки, рефакторинг, тесты и многое другое.
При подготовке пул-реквеста сосредоточьтесь на чем-то одном, например реализации компонента или устранение ошибки. Не стоит сразу реализовывать компонент, проводить рефакторинг кода, писать для того и другого тесты, обновляя при этом зависимости. Любой пул-реквест можно разделить на несколько небольших, упростив процесс проверки. В связи с этим самое время вспомнить о принципе единственной ответственности.
Например, перед нами стоит задача — реализовать функциональность, требующую создания конкретного компонента. В этом случае первый пул-реквест содержит только компонент, следующий за ним реализует тесты, а итоговый интегрирует этот компонент в базу кода.
Благодаря такому подходу в нужное время вы будете готовы к обсуждению различных вопросов.
- Правильно ли выполнена реализация компонента?
- Покрывают ли тесты все ключевые и связанные с ними пограничные случаи?
- Является ли API компонента содержательным и эргономичным?
Главное, чтобы пул-реквест не содержал более 200 строк. В редких случаях при изобилии шаблонного кода допустим также вариант и с большим их числом (например, при необходимости реализовать новые View и ViewController целесообразно разместить стандартную строго определенную часть в том же пул-реквесте). Для таких примеров можно с легкостью написать и 800 строк, при этом основная часть должна быть четко выделена.
4. Обновляйте документацию
Поскольку код нужно документировать, то при работе над тем или иным его фрагментом следует обновлять документацию, например в случае изменения сигнатуры публичной функции в результате добавления или удаления параметра.
Если мы задействуем новые API, то не обойтись без обновления README.md. В целом для отслеживания всех изменений в базе кода нужен CHANGELOG.md. А это еще одна часть документации, подлежащая актуализации.
Уделяя внимание этому важному аспекту при подготовке пул-реквеста, мы достигаем 2 цели:
- обновляем документацию;
- экономим время рецензента, избавляя его от необходимости писать такой комментарий, как “не забыть обновить CHANGELOG.md”.
5. Не допускайте опечаток
Как и в предыдущем случае, соблюдение этой рекомендации позволит сэкономить время рецензента. Дело в том, что опечатки затрудняют проверку пул-реквеста, каждый раз отвлекая на себя внимание.
Кроме того, рецензент должен их отмечать, затрачивая время на составление к ним комментария.
Благодаря паре следующих приемов об опечатках можно будет забыть.
- Проверяйте внесенные в код изменения более одного раза перед тем, как нажать кнопку “Create Pull Request” (“Создать пул-реквест”). При соблюдении совета #3 это не займет много времени, поскольку пул-реквест будет небольшим.
- Подключите средство проверки грамматики в Xcode. Для этого откройте данную среду разработки, кликните “Edit” (“Редактирование”) на панели инструментов, выберите сначала “Format” (“Форматирование текста”), затем “Spelling and Grammar” (“Правописание и грамматика”) и в завершении кликните “Check Spelling While Typing” (“Проверка правописания в процессе набора текста”).
После активации данной опции Xcode будет подчеркивать обычной красной волнистой линией опечатки как в комментариях, так и в коде.
Заключение
Итак, теперь вы знаете несколько приемов написания качественных пул-реквестов, облегчающих работу рецензентов. Действуя согласно приведенным рекомендациям вы не только демонстрируете уважение к своим коллегам, но и помогаете оптимизировать ревью кода. А все выше перечисленное, в свою очередь, способствует вашему профессиональному развитию.
Нельзя не упомянуть еще одно важное преимущество данного подхода — созданные в соответствии с ним пул-реквесты требуют написания меньшего числа комментариев, что приводит к ускорению цикла разработки и сокращению ее этапов. В результате у всех наблюдается возросшая продуктивность и удовлетворение от работы.
Читайте также:
Читайте нас в Telegram, VK и Яндекс.Дзен
Перевод статьи Riccardo Cipolleschi: 5 Tips To Create Better Pull Requests