Открывайте PR для ревьюера, который еще не знаком с вашим кодом

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

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

Я понял, что уже поступал так с кем-то другим.

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

Большинство людей пишут описания для самих себя. Они пишут «Refactored service layer» или «Fixed auth module». Это описания для людей, которые уже знают контекст.

Хорошее описание предназначено для того, кто ничего не знает.

Описание — это не просто резюме. Это тест. Если вы не можете объяснить свою работу, ваша работа не готова.

Теперь я использую шестичастную структуру для каждого нетривиального PR:

• Intent (Цель): Объясните, зачем нужен этот PR и какую проблему он решает. Если вы не можете этого написать, остановитесь. PR не готов. • Major changes (Основные изменения): Перечислите решения, которые влияют на архитектуру или существующее поведение. • Minor changes (Незначительные изменения): Перечислите очистку кода и переименования. Держите их отдельно от структурных изменений. • Impact (Влияние): Перечислите системы, которых это касается. Предоставьте карту «радиуса поражения» (blast radius). • Evidence (Доказательства): Перечислите, что вы запускали и какие тесты прошли. Покажите доказательства того, что вы проделали работу. • Uncertainties (Неопределенности): Укажите, в чем вы не уверены.

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

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

Описание — это последний шаг перед тем, как решить, стоит ли вообще открывать PR.

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

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

Если описание выдерживает проверку, PR готов.

Открывайте PR, ваш ревьюер еще не знаком с вами

Мы все через это проходили. Вы провели часы, а может и дни, доводя свой код до совершенства. Вы проводили рефакторинг, оптимизацию, добавляли тесты. Но все равно остается это грызущее чувство: «Достаточно ли это хорошо?»

Страх осуждения может парализовать. Мы ждем идеального момента, идеального кода, идеального PR. Но совершенство — это иллюзия.

Вот правда: лучший способ улучшить свой код — это получать обратную связь. А лучший способ получить обратную связь — это открыть PR.

Не ждите, пока вам покажется, что всё идеально. Идеально не будет никогда.

Открывайте PR. Получайте фидбек. Учитесь. Повторяйте.

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

Так что сделайте глубокий вдох, нажмите кнопку «Create Pull Request» и позвольте обучению начаться.

Дополнительное обучающее сообщество: https://t.me/GyaanSetuAi