내가 시도해본 코드 리뷰(Pull Request) 개선 방법

코드 리뷰(Pull Request)는 협업 개발 환경에서 중요한 과정입니다. 잘 진행된 코드 리뷰는 코드 품질을 높이고, 개발자의 성장에 기여하며, 팀의 생산성을 향상시킵니다. 하지만, 코드 리뷰가 비효율적으로 진행되면 오히려 개발 속도를 저하시킬 수도 있습니다. 이번 글에서는 제가 시도해 본 PR(Pull Request) 리뷰 개선 방법과 좋은 코드 리뷰 문화를 만드는 방법에 대해 다뤄보겠습니다.

1. 코드 리뷰를 잘하는 방법

코드 리뷰 좋다는 것은 공감하지만 실제로 시간이 많이 드는 작업이기도 합니다. 코드 리뷰를 잘하기 위해서는 리뷰하는데 시간이 적게 걸리는 것이 중요합니다. 구글의 코드리뷰 가이드를 읽어보는 것도 도움이 될 것입니다.

1.1 내가 리뷰이(Revee) 일 때

코드 리뷰를 요청하는 입장에서 리뷰어가 쉽게 이해할 수 있도록 PR을 준비하는 것이 중요합니다.

📌 리뷰 요청 시 고려할 점

PR 설명을 명확하게 작성하기
PR의 목적과 변경 사항을 이해하기 쉽도록 정리해야 합니다. 예를 들어:
- "이 PR에서는 XXX 기능을 추가했습니다. 이를 위해 A, B, C 파일을 수정했으며, XXX 문제를 해결하기 위해 YYY 방식을 적용했습니다."
리뷰 포인트를 남기기
리뷰어가 집중해야 할 부분을 알려주면 리뷰의 질이 올라갑니다. 예를 들어:
- "이 부분에서 A보다는 B 방식이 이후 변경 등 유지보수에 용이하다고 생각했지만, 가독성이 기존 톤과 맞지 않아 읽기 어렵다고 느껴져서 고민입니다. 더 좋은 의견 있다면 부탁드립니다."
PR 크기를 작게 유지하기
변경된 파일이 많아지면 리뷰어가 피로감을 느낄 수 있습니다. 한 PR에서 최대 10개의 파일 변경을 넘기지 않도록 노력하세요.

브랜치 전략을 세우기
브랜치를 잘 관리하면 PR 단위를 작게 유지할 수 있습니다. 예를 들어, 기능별 작업 브랜치를 만들고, 마스터 브랜치와의 차이를 명확하게 하세요.
- 워킹 브랜치 전략(Long Running Strategy)을 적용을 고민해 보는 것도 좋습니다.
- 기능별 작업 프랜치에 공통 모듈처럼 의존적인 작업 브랜치가 있다면 공통 모듈 작업을 진행하는 작업 브랜치 feature/MYJOB-1 에서 다음 기능 작업인 feature/MYJOB-2 브랜치를 만들어 feature/MYJOB-2 -> feature/MYJOB-1 -> main 순으로 순차적으로 진행한다면 diff가 작업한 부분만 보이기 때문에 코드 리뷰에 도움을 줄 수 있습니다.

1.2 내가 리뷰어(Reviewer) 일 때

코드를 리뷰하는 입장에서는 단순한 승인(approve)이 아니라, 질 좋은 피드백을 제공하는 것이 중요합니다.

📌 좋은 코드 리뷰를 위한 팁

명확한 질문과 의견을 남기기
- ❌ "이게 맞나요?" (X) → ✅ "이 부분은 XXX 때문이라고 이해했는데, YYY 방식으로 하면 더 좋지 않을까요?"
- ❌ "이거 이렇게 바꾸세요." (X) → ✅ "이 부분을 이렇게 변경하면 XXX 면에서 더 개선될 수 있을 것 같습니다. 어떻게 생각하시나요?"
비판이 아닌 개선 방향 제시하기
- 피드백을 줄 때는 상대방이 수용하기 쉽게 전달해야 합니다. 단순한 지적보다는 대안을 함께 제시하면 효과적입니다.
불필요한 이상적인 논의는 피하기
- 코드 리뷰는 실제 코드 개선을 위한 것이므로, PR 범위를 벗어난 이상적인 논의(예: "이거 차라리 리팩터링 하는 게 낫지 않을까요?")는 피하는 것이 좋습니다.
맹목적인 Approve 피하기
- 코드의 내용을 충분히 검토하지 않고 승인하는 것은 리뷰의 의미를 퇴색시킵니다. "어차피 문제없겠지"라는 생각보다는, 코드의 흐름을 읽고 의견을 남기는 것이 중요합니다. 코드 리뷰는 내가 이 코드의 머지를 승인하는 것이니 책임이 있습니다.
답이 없는 문제
- 개발은 A, B, C 중 기능 개발이나 문제 해결에 가장 적합한 방법을 선택하는 과정이라고 생각합니다. 코드 리뷰는 이러한 문제 해결 방식이 적절한지 함께 고민하는 과정입니다. 하지만 처음 코드 리뷰를 진행할 때는 각자의 선호하는 코드 스타일이나 컨벤션에 대한 피드백을 남기기 쉽고, 이는 리뷰 과정에서 피로도를 높일 수 있습니다.
  이러한 문제를 줄이기 위해서는 협업 담당자들이 코드 컨벤션 가이드를 만들고, 한 사람의 코드 스타일로 통일하는 것이 생산성 향상에 도움이 됩니다. 또한, 코드 컨벤션을 자동화하기 위해 Lint 도구를 도입하거나 pre-commit 훅을 활용하는 것도 좋은 방법입니다. 해결책이 명확하지 않은 경우, 팀원들과 논의하여 룰을 정하거나 자동화할 수 있는 방안을 고민해 보는 것이 좋습니다.

2. 좋은 코드 리뷰 문화를 만드는 방법

코드 리뷰를 단순한 코드 검토 과정이 아니라 팀 전체의 성장과 협업의 일환으로 바라보면 더욱 효과적입니다. 이를 위해 조직 차원에서 코드 리뷰 문화를 정립할 수 있습니다.

2.1 협업을 위한 브랜치 전략과 PR 시점 다듬기

기능 단위의 브랜치를 유지하기
- 개발 중인 기능을 작은 단위로 쪼개어 브랜치를 생성하고, 작은 단위로 PR을 보내면 코드 리뷰가 수월해집니다.
PR을 적절한 시점에 요청하기
- 너무 이른 PR은 리뷰어가 이해하기 어렵고, 너무 늦은 PR은 코드 변경 사항이 많아져 리뷰가 어려워질 수 있습니다. 적절한 타이밍을 찾는 것이 중요합니다.

2.2 PR 템플릿 도입하기

PR 요청 시 기본적으로 포함해야 하는 내용을 미리 정해두면 리뷰가 더욱 체계적으로 이루어질 수 있습니다. 예를 들어 PR 템플릿에 아래와 같은 항목을 추가할 수 있습니다. 이 외에도 PR 타이틀, 라벨 등을 정의하면 열려있는 PR의 상태를 한눈에 파악하는 데 도움이 됩니다. PR 요청 시 기본적으로 포함해야 하는 내용을 미리 정해두면 리뷰가 더욱 체계적으로 이루어질 수 있습니다. 예를 들어 PR 템플릿에 아래와 같은 항목을 추가할 수 있습니다.

## 변경 사항 요약
- (어떤 변경을 했는지 간략히 설명)
## 변경 이유
- (왜 이 변경이 필요한지 설명)
## 테스트 방법
- (어떤 방식으로 테스트했는지 설명)
## 리뷰 포인트
- (리뷰어가 중점적으로 봐야 할 부분)

2.3 Code Owners 설정하기

GitHub의 CODEOWNERS 파일을 활용하면 특정 파일이나 폴더에 대한 리뷰어를 자동으로 지정할 수 있습니다. 이를 활용하면 팀원들이 맡고 있는 도메인에 따라 코드 리뷰가 자동으로 할당됩니다.

2.4 GitHub Actions를 활용한 코드 리뷰 보조

코드 리뷰를 도와줄 수 있는 자동화 도구를 활용하면 코드 품질을 유지하는 데 도움이 됩니다.

Lint 체크: 코드 스타일이 맞는지 자동으로 확인
Test 자동 실행: 테스트를 자동화하여 코드 변경이 기존 기능에 영향을 주는지 확인
PR Description 자동 채우기: PR 템플릿을 자동으로 적용

2.5 점진적인 개선

한번 정한 룰이나 가이드는 쉽게 바꾸기 어렵다는 생각 때문에 아예 만들지 않는 경우도 많습니다. 하지만 좋은 코드 리뷰 문화를 만들기 위해 가이드를 세웠다면, 그것이 실제로 잘 지켜지고 있는지 주기적으로 점검하는 것이 중요합니다. 만약 가이드가 잘 지켜지지 않는다면 그 이유를 팀원들과 논의하고, 개선 방안을 찾아가는 과정이 필요합니다. 작은 변화라도 지속적으로 개선해 나가면 더욱 효과적인 코드 리뷰 문화를 정착시킬 수 있습니다.

결론

코드 리뷰는 단순히 코드의 오류를 찾는 과정이 아니라, 더 나은 코드를 만들기 위한 협업 과정입니다. 리뷰이와 리뷰어가 서로의 입장을 고려하여 PR을 준비하고, 질 좋은 피드백을 제공하는 것이 중요합니다. 또한 브랜치 전략, PR 템플릿, 자동화 도구를 활용하여 코드 리뷰 문화를 개선하면 더욱 효율적인 협업이 가능해집니다.

PR 리뷰를 잘하고, 코드 리뷰 문화를 정착시키면, 개발팀 전체의 생산성과 코드 품질이 향상될 것입니다.

조각 기록