При отправке pull request есть два места для пояснений: описание PR и комментарии в изменяемом коде. Важно понимать, какую информацию оставлять в каждом из них.
Описание PR — это место, где вы обосновываете, почему изменение должно быть принято. В заголовке формулируют проблему или добавляемую функцию. Хороший заголовок облегчает поиск связанных изменений при расследовании регрессий; он должен быть достаточно конкретным, чтобы сразу дать понять, к каким подсистемам относится изменение.
Что писать в описании PR
- Причина изменения и как оно решает проблему.
- Детали проверки: какие тесты проведены, есть ли скриншоты «до/после», какие юнит-тесты добавлены.
- Обсуждение альтернативных вариантов проектирования и аргументы в пользу выбранного решения (например, почему другие варианты отклонены как слишком рискованные).
- Уточнения, релевантные для ревью в момент отправки PR: какие проверки выполнены, какие предпосылки учтены (например, проверены ли все места вызова исправляемой функции).
Описание PR — временное, привязанное к моменту отправки: утверждения о том, что на момент проверки были просмотрены все вызовы функции или что с определённой командой согласовано требование, полезны для ревью, но перестанут быть корректными после изменений в кодовой базе.
Что писать в комментариях в коде
Комментарии в коде служат для объяснения самого кода и должны быть долговечными. Они помогают будущим разработчикам понять предназначение функции, контракт её входных данных, предусловия, побочные эффекты и примеры использования.
- Документирование формата данных или схемы, которую принимает функция (это важно и через год, и через два).
- Описание предусловий и ограничений работы функции, ожидаемых значений аргументов и возвращаемых значений.
- Указание сценариев использования как примера, но без утверждений, которые быстро устареют — например: «Этот код используется, в том числе, компонентом Doodad», можно указать как один из сценариев использования, но формулировать нейтрально, чтобы комментарий оставался актуальным, если Doodad перестанет полагаться на эту возможность.
Комментарий в коде должен иметь смысл сам по себе, без необходимости читать описание PR. Избегайте записей, которые ссылаются на текущее состояние разработки или на временные обстоятельства внедрения.
Примеры различий
Утверждение «Я проверил все вызовы этой функции, и это был единственный, который передавал неправильный флаг» — место для описания PR. Это обосновывает корректность изменения в момент ревью, но перестанет быть верным после возможных последующих изменений.
Утверждение «JSON‑схема, принимаемая этой функцией, документирована здесь» — место для комментария в коде (и для внутренней документации в репозитории). Это объясняет, как пользоваться функцией и остаётся релевантным длительное время.
Утверждение «Компонент Doodad воспользуется инверсией полярности» следует помещать в описание PR как обоснование срочности или причины изменения. В коде стоит нейтрально отметить, что один из сценариев использования — Doodad, не делая предположений о будущем поведения этого компонента.
Практический совет по размещению комментариев
Если комментарий относится к текущему процессу принятия решения или верификации, ставьте его в описание PR. Если комментарий описывает контракт, формат или постоянное поведение функции — оставляйте его в коде. Комментарий возле кода должен быть самостоятельным и понятным без контекста PR: например, при устаревании API поместите в старую функцию пояснение, что её можно удалить после миграции клиентов, и укажите критерий завершения миграции в виде ссылки на задачу внутри проекта (без внешних ссылок).
Такой подход помогает сохранить полезную и корректную историю намерений: описание PR фиксирует обоснование и проверки в момент ревью, а комментарии в коде обеспечивают долговечную документацию для будущих разработчиков.