리뷰 코멘트와 PR 소통

같은 지적이라도 어떻게 쓰느냐에 따라 받아들이는 사람의 반응이 완전히 달라진다. 좋은 리뷰 코멘트는 무엇이 문제인지, 왜 그런지, 어떻게 바꾸면 좋을지가 한 번에 전달되고, 그 지적이 꼭 고쳐야 하는 것인지 취향인지까지 분명하다. 무엇을 볼지는 코드 리뷰 원칙과 체크리스트에 정리했다.

「명령 대신 요청, 판단 대신 원칙」은 백명석의 「한번 듣고 평생 써먹는 코드 리뷰 노하우」(OKKY 세미나, 2022.01) 강연에서 정리했다.

좋은 리뷰 코멘트

1. 이유와 대안을 함께

❌ 이거 별로네요.
✅ 이 변수는 재할당되지 않아서 const로 선언하면 의도가 더 분명해질 것 같아요.
   const alert = { ... }

2. 단정 대신 질문으로

작성자에게 이유가 있을 수 있다. "왜 이렇게 했나요?"라고 물으면 몰랐던 맥락을 듣게 되거나, 작성자가 스스로 개선점을 찾는다.

❓ alert 객체를 따로 변수에 담은 이유가 궁금합니다. $emit 인자로 바로 넘겨도 되지 않을까요?

질문은 가져온 코드도 내 코드처럼 이해하고 고쳐서 써야 한다는 점을 작성자가 스스로 확인하게 한다.

명령 대신 요청, 판단 대신 원칙

3. 중요도를 표시하기

모든 코멘트가 같은 무게로 보이면 작성자는 무엇부터 고칠지 모른다. 접두사로 구분하면 좋다.

4. 칭찬도 코멘트로

잘 짠 부분, 배운 부분을 짚어 주는 것도 리뷰다. 리뷰가 지적만 오가는 자리가 되지 않게 한다.

PR에서 자주 쓰는 약어

리뷰를 받는 쪽

• PR을 올리기 전 준비(작게 나누기, 무엇을·왜 바꿨는지 설명하기, 먼저 스스로 읽기)는 코드 리뷰 원칙과 체크리스트의 「작성자와 리뷰어가 할 일」에 있다. 설명 양식은 아래 PR 템플릿을 쓴다.
• 코멘트는 나에 대한 평가가 아니라 코드에 대한 의견이다. 반영했으면 어떻게 바꿨는지, 반영하지 않으면 이유를 답글로 남긴다.
• 리뷰에서 나온 개선 사항은 다음 리뷰 전까지 반영해 온다.

PR 템플릿 예시

저장소의 .github/pull_request_template.md에 두면 PR을 열 때마다 자동으로 채워진다.

### 작업 개요
<!-- 예: 고양이가 야옹 소리를 내도록 수정 -->
 
### 관련 이슈
<!-- 예: #123 -->
 
### 작업 분류
- [ ] 버그 수정
- [ ] 신규 기능
- [ ] 리팩터링 / 구조 변경
 
### 작업 상세 내용
<!-- 1. 네 발 짐승 클래스에 울음 함수 추가 -->
 
### 확인 방법
<!-- 테스트, 스크린샷 등 -->
 
### 생각해 볼 문제
<!-- 리뷰어와 함께 고민하고 싶은 점 -->

저장소 설정(브랜치 보호, CODEOWNERS, 라벨)은 GitHub 협업 설정 참고.

핵심 정리

• 코멘트 = 문제 + 이유 + 대안(예시 코드). 단정보다 질문.
• must / suggestion / nit 으로 중요도를 구분한다.
• LGTM(승인), NIT(사소함), PTAL(다시 봐 주세요), IMO(개인 의견)는 꼭 알아 둔다.
• PR은 작게, 설명은 충분히, 답변은 성실하게.

관련 노트: 친절한 엔지니어링