Как упростить кодревью
Делюсь проверенными на личном опыте способами упростить ревью вашего кода и в целом повысить культуру кодревью в компании.
📏 Размер пулреквестов — 80% успеха
Чем меньше пулреквесты — тем лучше. Большие PR демотивируют ревьюеров и снижают качество ревью, потому что сложно удерживать объём изменений в голове.
Если получается большой пулреквест, возможно вы смешали в нём правки в разных частях системы, требуемые для решения исходной задачи. Такие правки обычно можно разбить на отдельные PR: например, отделить новые UI-компоненты от реализации страницы с их использованием.
Ещё один случай больших PR — рефакторинги. Обычно их можно разделить на две части:
1. Содержательные изменения в какой-то части системы
2. Шаблонное обновление остального кода
Отделите первое от второго, и вы сэкономите время и силы ревьюеров, которым не очень важен бойлерплейт.
В завершение про размер пулреквестов: не поддавайтесь соблазну докинуть новую функциональность в уже открытые PR. Новая функциональность — новый пулреквест. Это опять же про самодостаточные изменения и внимание ревьюеров, которое не бесконечно.
📝 Описание изменений
Ревьюерам сильно поможет внятное описание ваших изменений. Какую задачу вы решали, почему решили её именно так, на что стоит обратить внимание.
Не ленитесь описать это прямо в PR, не все открывают прилинкованные задачи, и в них может не хватать контекста.
В идеале описание нужно сопроводить ссылкой на тестовый стенд, где изменения можно оценить вживую. Если стенда нет, позаботьтесь о том, чтобы проект было легко запустить локально, и сопроводите описание скриншотами конечных изменений (актуально для фронтендеров).
Если пулреквест содержит неочевидные решения или хаки, от которых не избавиться, заранее сопроводите их комментариями прямо в коде — для ревьюеров и для будущих поколений, которые будут читать этот код.
Не стесняйтесь сопроводить PR собственными комментариями на отдельных участках кода, чтобы:
— указать порядок чтения;
— прояснить мотивацию к конкретным изменениям;
— явно обратить внимание на сложные места;
— явно запросить обратную связь, если сомневаетесь в своём коде.
🕵️ Ревью собственных пулреквестов
Прежде чем запрашивать ревью у других разработчиков, просмотрите свои изменения, будто кто-то другой запросил у вас ревью. Так вы сэкономите своё и чужое время, сразу обнаружив очевидные косяки вроде опечаток или забытого кода для отладки.
🔔 Уведомления о ревью
Чтобы вам и ревьюерам не приходилось вручную следить за запросами ревью, комментариями, апрувами и прочим, настройте уведомления о них в рабочем мессенджере. Например, я использую интеграцию GitHub и Slack.
🤝 Явное обозначение намерений в комментариях
У вас будет больше взаимопонимания, если ревьюер явно обозначит, какие замечания считает критичными, а какие можно проигнорировать.
Conventional Comments — хороший пример готовых соглашений для обозначения намерений.
Делюсь проверенными на личном опыте способами упростить ревью вашего кода и в целом повысить культуру кодревью в компании.
📏 Размер пулреквестов — 80% успеха
Чем меньше пулреквесты — тем лучше. Большие PR демотивируют ревьюеров и снижают качество ревью, потому что сложно удерживать объём изменений в голове.
Если получается большой пулреквест, возможно вы смешали в нём правки в разных частях системы, требуемые для решения исходной задачи. Такие правки обычно можно разбить на отдельные PR: например, отделить новые UI-компоненты от реализации страницы с их использованием.
Ещё один случай больших PR — рефакторинги. Обычно их можно разделить на две части:
1. Содержательные изменения в какой-то части системы
2. Шаблонное обновление остального кода
Отделите первое от второго, и вы сэкономите время и силы ревьюеров, которым не очень важен бойлерплейт.
В завершение про размер пулреквестов: не поддавайтесь соблазну докинуть новую функциональность в уже открытые PR. Новая функциональность — новый пулреквест. Это опять же про самодостаточные изменения и внимание ревьюеров, которое не бесконечно.
📝 Описание изменений
Ревьюерам сильно поможет внятное описание ваших изменений. Какую задачу вы решали, почему решили её именно так, на что стоит обратить внимание.
Не ленитесь описать это прямо в PR, не все открывают прилинкованные задачи, и в них может не хватать контекста.
В идеале описание нужно сопроводить ссылкой на тестовый стенд, где изменения можно оценить вживую. Если стенда нет, позаботьтесь о том, чтобы проект было легко запустить локально, и сопроводите описание скриншотами конечных изменений (актуально для фронтендеров).
Если пулреквест содержит неочевидные решения или хаки, от которых не избавиться, заранее сопроводите их комментариями прямо в коде — для ревьюеров и для будущих поколений, которые будут читать этот код.
Не стесняйтесь сопроводить PR собственными комментариями на отдельных участках кода, чтобы:
— указать порядок чтения;
— прояснить мотивацию к конкретным изменениям;
— явно обратить внимание на сложные места;
— явно запросить обратную связь, если сомневаетесь в своём коде.
🕵️ Ревью собственных пулреквестов
Прежде чем запрашивать ревью у других разработчиков, просмотрите свои изменения, будто кто-то другой запросил у вас ревью. Так вы сэкономите своё и чужое время, сразу обнаружив очевидные косяки вроде опечаток или забытого кода для отладки.
🔔 Уведомления о ревью
Чтобы вам и ревьюерам не приходилось вручную следить за запросами ревью, комментариями, апрувами и прочим, настройте уведомления о них в рабочем мессенджере. Например, я использую интеграцию GitHub и Slack.
🤝 Явное обозначение намерений в комментариях
У вас будет больше взаимопонимания, если ревьюер явно обозначит, какие замечания считает критичными, а какие можно проигнорировать.
Conventional Comments — хороший пример готовых соглашений для обозначения намерений.
👍38
С наступающим 2025
Давно ничего не писал, собрался с силами и вернулся к давно забытому жанру итогов года: https://andrew-r.ru/notes/bye-2024/
Давно ничего не писал, собрался с силами и вернулся к давно забытому жанру итогов года: https://andrew-r.ru/notes/bye-2024/
andrew-r.ru
Пока, 2024
Новый дом, новая работа, поездки, потери и рефлексия
❤30👍15👎4
Мониторинг падений браузера
В рабочем чате недавно интересовались, можно ли как-то отследить падение браузерной вкладки с нашим веб-приложением. Я о таких способах не знал, поэтому из любопытства отправился гуглить.
Нетривиальность задачи заключается в том, что падение неожиданно обрывает выполнение кода вашего приложения, так что стандартные подходы вроде обработки какого-то глобального события неприменимы, ведь для обработки события нужен живой процесс, исполняющий ваш код.
Как выяснилось, существует экспериментальный Reporting API, позволяющий отслеживать как падения, так и другие виды проблем, например, нарушения политик безопасности (вроде Content Security Policy) и использование устаревших фич.
Reporting API предоставляет два основных способа получения отчётов о проблемах:
1. Глобальный класс ReportingObserver, позволяющий подписаться на предупреждения и как-либо их обрабатывать через JavaScript; так как это клиентский API, он не отслеживает падения.
2. HTTP-заголовок Reporting-Endpoints, задающий серверные эндпойнты, на которые бразуер должен отправлять собранные отчёты; этот способ покрывает все виды отчётов, включая падения.
На портале Chrome for Developers есть хороший обзор Reporting API.
API всё ещё не стабилен, спецификация находится в статусе черновика, и пока она реализована не во всех основных браузерах. Несмотря на все эти оговорки, аналогов Reporting API нет, и его уже используют, например, в Figma.
В рабочем чате недавно интересовались, можно ли как-то отследить падение браузерной вкладки с нашим веб-приложением. Я о таких способах не знал, поэтому из любопытства отправился гуглить.
Нетривиальность задачи заключается в том, что падение неожиданно обрывает выполнение кода вашего приложения, так что стандартные подходы вроде обработки какого-то глобального события неприменимы, ведь для обработки события нужен живой процесс, исполняющий ваш код.
Как выяснилось, существует экспериментальный Reporting API, позволяющий отслеживать как падения, так и другие виды проблем, например, нарушения политик безопасности (вроде Content Security Policy) и использование устаревших фич.
Reporting API предоставляет два основных способа получения отчётов о проблемах:
1. Глобальный класс ReportingObserver, позволяющий подписаться на предупреждения и как-либо их обрабатывать через JavaScript; так как это клиентский API, он не отслеживает падения.
2. HTTP-заголовок Reporting-Endpoints, задающий серверные эндпойнты, на которые бразуер должен отправлять собранные отчёты; этот способ покрывает все виды отчётов, включая падения.
На портале Chrome for Developers есть хороший обзор Reporting API.
API всё ещё не стабилен, спецификация находится в статусе черновика, и пока она реализована не во всех основных браузерах. Несмотря на все эти оговорки, аналогов Reporting API нет, и его уже используют, например, в Figma.
👍28❤5