Редакционный разбор по материалу The Old New Thing от 12 августа 2026 года. Первоисточник.
Когда вы отправляете pull request, есть два места, где вы можете объяснить, что вы делаете и почему. Одно — описание pull request, другое — комментарии в коде, который вы изменяете. Важно понимать разницу между ними.
Pull request — это место, где вы обосновываете, почему ваше изменение должно быть принято. В заголовке вы формулируете проблему, которую исправляете, или функцию, которую добавляете. В большом кодовой базе может потребоваться быть чуть более конкретным.
Примеры:
- Добавить поддержку инверсии полярности виджета
- Исправить падение виджета при двукратной смене полярности в короткий промежуток времени
Когда кто-то ищет регрессию, он будет просматривать все PR, которые недавно попали в ветку, и хороший заголовок поможет ему легче определить, какие изменения с высокой вероятностью являются источником проблемы. Например, если кто-то расследует падение «doodad», он может посмотреть PR «Добавить поддержку инверсии полярности виджета», потому что их doodad использует виджеты, и возможно проблема вызвана виджетом с обратной полярностью, который их doodad некорректно обрабатывает. С другой стороны, они уделят меньше внимания исправлению падения при смене полярности виджета, потому что это вряд ли причина падения doodad. И если их doodad вообще не использует виджеты, они могут просто пропустить оба PR.
Если бы PR имел исходный заголовок «Добавить поддержку инверсии полярности» без упоминания виджетов, команде, расследующей регрессию в гаджетах, пришлось бы вдаваться в детали PR (потому что у гаджетов тоже есть полярность), только чтобы понять, что речь о полярности виджетов, а не гаджетов.
Описание PR рассказывает о причине проблемы и о том, как вы её исправили и проверили. Это информация, относящаяся к конкретному моменту времени, где вы убеждаете рецензента, почему изменение необходимо и почему именно ваша реализация корректна. Обсудите альтернативные варианты проектирования и почему они были отклонены (например, потому что они были слишком рискованными). Покажите скриншоты до и после, подтверждающие, что проблема устранена. Подтвердите, что связанная документация и формальности выполнены, например юнит-тесты. Может существовать стандартная форма для этого, такая как «шаблон для checkin». Часто чем ближе проект к релизу, тем строже требования к документации. Например, на поздней стадии может потребоваться подтвердить, что команда по управлению релизом признала, что баг соответствует критериям баг-бара.
Иными словами, описание PR — это утверждение, относящееся к моменту времени, предоставляющее информацию, релевантную для самого код-ревью. Это упражнение в убедительном письме: вы пытаетесь убедить одобряющего принять ваше изменение.
Комментарии в коде служат для обсуждения самого кода. Как правильно вызывать эту функцию? Какие у неё специфические предусловия? Эта информация долговечна: она остаётся полезной и после завершения pull request.
Давайте упражнение: я приведу несколько фрагментов текста, а вы скажите, куда их поместить.
Это реальные комментарии (подходящим образом редактированные) из PR, которые я рецензировал.
«Я проверил все вызовы этой функции, и это был единственный, который передавал неправильный флаг.»
Это нужно поместить в описание pull request. Это обосновывает, почему ваше изменение корректно, и в частности отвечает на вопрос, который рецензент, вероятно, задаст: «Отлично, вы исправили этого одного вызова функции, но есть ли другие вызовы, которые делают ту же ошибку?» Помещать такое утверждение в код было бы ошибкой, потому что оно верно только на момент создания PR. После слияния кто-то может добавить новый вызов функции, передающий неправильный флаг, и тогда ваше утверждение уже не будет верным.
«JSON-схема, принимаемая этой функцией, документирована здесь.»
Это следует поместить в код. Это объясняет, как правильно использовать функцию. Эта информация важна не только в момент отправки PR, но и в неопределённом будущем (по крайней мере, пока вы не измените функцию или схему).
«Компонент Doodad воспользуется инверсией полярности.»
Это следует поместить в описание pull request. Это обосновывает, почему вам нужно реализовать инверсию полярности сейчас. Если поместить это в код, время будущее будет означать, что мы всё ещё ждём Doodad. Будущие изменения в Doodad могут привести к тому, что они перестанут полагаться на инверсию полярности; когда это произойдёт, они вряд ли придут и обновят комментарий в чужом компоненте. Комментарий также предполагает, что если вы подтвердите с командой Doodad, что им больше не нужна инверсия полярности, безопасно удалить поддержку инверсии полярности, что может быть неверно, если другие компоненты начали использовать эту функцию.
Тем не менее, знать, что Doodad является целевой аудиторией функции, стоит отметить для будущего.
Дополнительные замечания:
Ещё одно, что следует учитывать при написании комментариев в коде — комментарий должен иметь смысл без описания PR. Допустим, вы пишете функцию с намерением устаревания старой функции, которую она заменяет. Не добавляйте такой комментарий в новую функцию:
// Возле НОВОГО API такой комментарий двусмысленен:
// После миграции всех клиентов оставить эту функцию.Это не будет иметь смысла для того, кто видит комментарий, не видя и не помня PR, который его ввёл. Будет казаться, что комментарий говорит: «Когда X произойдёт, не предпринимать никаких действий.»
Вместо этого следует поместить комментарий на старую функцию:
// Старый API: удалить после миграции всех вызывающих мест
// на новый API; критерий завершения указан в задаче миграции.Это самостоятельный пример того же принципа: условие удаления относится к старому API. Комментарий возле новой функции не должен создавать впечатление, что удалять нужно её. Контекст проверки конкретного PR при этом остаётся в описании изменения.