PR을 여세요, 리뷰어가 아직 당신의 코드를 만나지 못했습니다
최근에 규모가 큰 풀 리퀘스트(PR)를 리뷰했습니다. AI를 사용하여 코드를 작성했더군요. 세 개의 다른 기능이 사용 중인 모듈을 변경했습니다. 설명은 단 한 문장이었습니다. 파일 이름은 적혀 있었지만, 왜 변경했는지는 나와 있지 않았습니다.
작업을 시작하기도 전에 변경 사항을 파악하는 데 15분을 썼습니다. 의도를 찾아야 했고, 리스크를 찾아야 했으며, 중요한 파일과 노이즈를 분리해야 했습니다.
문득 제가 예전에 다른 사람에게도 똑같이 행동했다는 사실을 깨달았습니다.
코드를 작성할 때, 당신은 모든 맥락(context)을 머릿속에 담고 있습니다. 왜 모듈을 분리했는지, 처음에 무엇을 시도했는지, 어떤 부분이 확신이 서지 않는지 모두 알고 있습니다.
대부분의 사람들은 자신을 위해 설명을 작성합니다. "서비스 레이어 리팩토링" 또는 "인증 모듈 수정"과 같이 말이죠. 이런 설명은 이미 맥락을 알고 있는 사람들을 위한 것입니다.
좋은 설명은 아무것도 모르는 사람을 위한 것입니다.
설명은 단순한 요약이 아닙니다. 그것은 하나의 테스트입니다. 자신의 작업 내용을 설명할 수 없다면, 그 작업은 아직 준비되지 않은 것입니다.
이제 저는 사소하지 않은 모든 PR에 대해 6단계 구조를 사용합니다:
• Intent: 이 PR이 왜 존재하는지, 어떤 문제를 해결하는지 설명하세요. 이를 작성할 수 없다면 멈추세요. 그 PR은 아직 준비되지 않은 것입니다. • Major changes: 아키텍처나 기존 동작에 영향을 미치는 결정 사항들을 나열하세요. • Minor changes: 정리(cleanup) 및 이름 변경 사항을 나열하세요. 구조적 변경 사항과는 분리해서 작성하세요. • Impact: 이 변경이 영향을 미치는 시스템들을 나열하세요. 영향 범위(blast radius)를 파악할 수 있는 지도를 제공하세요. • Evidence: 무엇을 실행했는지, 어떤 테스트를 통과했는지 나열하세요. 작업을 완료했다는 증거를 보여주세요. • Uncertainties: 확신이 서지 않는 부분을 명시하세요.
불확실성을 인정하면 리뷰어를 돕게 됩니다. 리뷰어는 어디를 주의 깊게 봐야 할지 알게 됩니다. 잘 작동하는 부분에 시간을 낭비하지 않게 됩니다.
불확실성을 말할 수 없다면, 자신의 코드에 대해 충분히 깊게 고민하지 않은 것입니다.
설명은 PR을 열지 말지 결정하기 전의 마지막 단계입니다.
의도를 이해하는 리뷰어는 어려운 질문에 시간을 씁니다. 의도를 추측해야 하는 리뷰어는 쉬운 질문에 시간을 씁니다. 그들은 이것이 맞는지 묻는 대신, 이것이 무엇인지 묻게 됩니다.
아직 당신의 코드를 만나지 못한 리뷰어를 위해 작성하세요. 질문에 답하기 위해 그 자리에 없을 것처럼 작성하세요. 마치 3일 뒤에 작업에 대한 기억이 전혀 없는 상태에서 이 글을 읽는 것처럼 작성하세요.
설명이 충분하다면, 그 PR은 준비된 것입니다.
출처: https://dev.to/jeelvankhede/open-the-pr-your-reviewer-has-not-met-yet-4gfe
선택 학습 커뮤니티: https://t.me/GyaanSetuAi