좋은 PR을 작성하는 방법

코드 리뷰를 하다 보면 PR만 보고는 이 코드가 왜 필요한지, 어떤 문제를 해결하려는 것인지 파악하기 어려운 경우가 있다. 결국 리뷰어는 Jira 티켓을 찾아보거나, 기획 문서를 뒤지거나, 슬랙에서 관련 대화를 검색하게 된다. 이런 상황이 반복되면 리뷰어는 피로감을 느끼고, 코드의 구조나 컨벤션 같은 표면적인 부분만 리뷰하게 된다.

좋은 PR은 리뷰어가 기획을 몰라도 코드 리뷰를 할 수 있을 정도로 충분한 맥락을 제공해야 한다고 생각한다.

맥락이 부족한 PR의 문제

맥락이 부족한 PR에서는 다음과 같은 리뷰가 반복된다.

• 변수명이 명확하지 않다
• 이 함수는 너무 길다
• 여기에 타입을 추가해야 한다
• 코드 스타일이 컨벤션과 다르다

물론 이런 리뷰도 중요하지만, 정작 비즈니스 로직이 올바른지, 엣지 케이스가 처리되었는지, 더 나은 설계 방법은 없는지에 대한 논의는 하기 어렵다. 리뷰어가 코드의 의도를 파악하지 못하기 때문이다.

좋은 PR이 담아야 할 것들

PR에는 리뷰어가 알아야 할 기본 정보를 담아야 한다. 다음의 내용들을 포함하면 좋다.

배경과 목적

왜 이 작업이 필요한지 설명한다. 관련 티켓이 있다면 링크를 첨부하고, 간단하게 요약해서 적어준다. 티켓을 열어보지 않아도 대략적인 맥락을 파악할 수 있어야 한다.

변경 사항 요약

어떤 부분이 어떤 이유로 수정되었는지 정리한다. 핵심적인 변경사항을 먼저 언급하고, 부가적인 변경사항은 별도로 구분해서 적어주면 리뷰어가 중요한 부분에 집중할 수 있다.
UI 변경이 있다면 스크린샷이나 GIF를 첨부한다. 리뷰어가 직접 실행하지 않아도 변경된 동작을 확인할 수 있다.

논의사항

리뷰어가 특별히 봐줬으면 하는 부분이나, 확신이 없어서 의견을 듣고 싶은 부분을 명시한다. 이렇게 하면 리뷰어가 어디에 집중해야 하는지 알 수 있다.

PR 크기도 중요하다

아무리 설명을 잘 적어도 PR이 너무 크면 리뷰가 어렵다. 변경된 파일이 수십 개이고 코드가 수천 줄이면 리뷰어는 부담을 느낀다. 가능하면 PR을 작은 단위로 나누어서 올리는 것이 좋다.

큰 기능을 개발할 때는 기능 단위로 PR을 분리하거나, 리팩토링과 기능 추가를 별도의 PR로 나누는 방법이 있다. 작은 PR은 리뷰가 빠르고, 피드백 반영도 쉽다.

마치며

좋은 PR을 작성하는 것은 쉽지 않다. 코드를 작성하는 시간 외에 PR을 정리하는 시간이 추가로 필요하기 때문이다. 하지만 이 시간이 팀 전체의 생산성을 높인다고 생각한다.