[Team] 코드 리뷰 코멘트는 어떻게 작성하면 좋을까? 코드 리뷰 원칙 들여보기

0. 들어가기에 앞서

코드의 품질 향상은 물론 컨벤션 체크까지 할 수 있는 코드 리뷰!
그런데 코멘트를 잘 하기란 쉽지 않죠 😞

• 코드리뷰란, 말 그대로 개발자가 작성한 코드를 다른 개발자가 리뷰(피드백)하는 과정을 말한다.
• 이 과정을 거치면 개발자는 본인이 발견치 못한 실수(오타, 버그 등)를 초기에 대응할 수 있고
• 팀 내 정해진 컨벤션 규칙을 유지하고 기술 부채를 줄일 수 있다.
• 또한, 다수의 개발자가 참여하기에 해당 코드를 다른 관점에서 보고 더 나은 해결방법을 제시할 수도 있다.
• 하지만 리뷰를 하는 과정에서 코멘트로 인해 팀원 간 감정이 상하는 경우가 발생하곤 하는데…
• 이번시간에는 더 나은 리뷰 코멘트를 위해 구글, 뱅크샐러드, 카카오, 토스랩팀의 코멘트 원칙을 살펴보았다.

1. 리뷰 코멘트, 어떻게 작성하면 좋을까?

1) 전제

우선 리뷰 코멘트 원칙을 알기 전에, 아래 사항을 염두해두자

1. 코드리뷰도 커뮤니케이션이다.
2. 코드를 리뷰할 것! 리뷰요청자의 인격체를 리뷰하면 안된다.
3. 코드 리뷰는 함께 성장하는 과정이다.
4. 코드 리뷰가 관성적인 숙제가 되어선 안된다. 이 과정에서 배움을 얻는 게 중요하다.
5. 개발팀 내에서 코드 리뷰 관련 원칙과 문화를 세워야 한다.

2) 리뷰 코멘트 잘하는 방법

(1) 예의를 지켜주세요

• 코드리뷰도 사람 간의 커뮤니케이션이므로, 부드러운 어투 + 존댓말을 사용해야 한다.
• '하세요' 와 같은 명령조, ‘굳이', ‘왜 하셨나요?’와 같은 부정적인 단어의 사용을 지양해야 한다.

나쁜 예시) 

- 굳이 코드를 왜 이방식으로 짰죠?
- 이중 반복문 쓰면 성능이 느릴 텐데, 더 알아보고 코딩하면 좋지 않았을까요?
- 지난 번에도 유사한 실수가 있었는데 개선의 여지가 부족해보이네요
- 여기 수정하세요

• 코드 수정을 요청할 때는 '하는게 어떨까요?', '하는 게 더 좋습니다'와 같은 말투를 사용하자.

좋은 예시) 

- A 상황을 커버하기 위해 추가한 코드로 보이네요, 
그런데 이 로직을 따르게 될 시 메모리 이슈가 발생할 수 있어요, B방식으로 진행해보는 건 어떨까요?

(2) 코멘트 작성시, 그 이유나 근거를 설명해주세요

• 리뷰어가 코드에 개선의 필요성을 느껴 코멘트를 남겼다면, 충분한 이유를 제공하는 게 중요하다.

나쁜 예시)

- 이중 조건문을 사용해서 얻는 이점이 전혀 없는데 왜 쓰셨나요?

• 코멘트에 대한 근거가 부족하다면 리뷰 요청자는 개선의 필요성을 느끼기 어렵고,
• 코멘트를 수용한다고 해도 리뷰요청자가 스스로 생각하고 학습할 계기를 제공할 수 없다.

좋은 예시)

- 해당 코드에서 이중 조건문의 경우, 시스템에 복잡성을 추가하고 있습니다. 
또한, 빈 입력 배열이나 항목이 어떤 조건도 충족하지 않을 때와 같은 특이 사례를 커버하기 어려워보여요
두 가지 조건을 기반으로 XXX 방식으로 처리하는 게 성능 향상과 특이 케이스 처리에서 유리합니다.

(3) 정답보다는 방향성을 제공해주세요

• 코드 리뷰를 하는 목적 중 하나는, 함께 성장하기 위함이다.
• 코드의 정답을 바로 제공한다면 리뷰 속도는 빨라지지만, 리뷰요청자가 스스로 고민하고 개선 방법을 찾을 수 있는 기회가 줄여든다.
• 한 예시로 반복문에 대한 코드 리뷰를 남긴다고 가정해보았을 때…

const result = [];

arr.forEach(element => {
  if(element % 3 === 0) {
    result.push(element);
  }
});

• 바로 정답을 제공해주기 보다는…

나쁜 예시)

“arr.filter(element => element % 3 === 0);으로 사용하세요."

• 키워드(filter)를 제공하여 스스로 검색하고 방법을 찾도록 피드백 하는 게 중요하다.
• 이 과정을 거치면 리뷰요청자는 유사한 코드를 만났을 때, 동작 방식을 이해하고 더 나은 코드를 작성할 수 있게 된다.

좋은 예시)

자바스크립트에는 배열에는 다양한 내장 메서드들이 존재하는데요,
그중 filter 메서드를 활용해 보는 건 어떨까요?
해당 메서드를 활용하면 코드량을 줄일 수 있고 가독성도 높일 수 있습니다.

(4) 감정적인 논쟁은 좋지 않아요

• 코드 리뷰 과정에서 견해의 차이로 인해 논쟁이 발생할 수 있다.
• 단 이 논쟁이 감정적인 논쟁이 된다면, 코드 개선이라는 목적보다는 ‘내가 맞아!’가 되는 경우가 있다.
• 만약 감정적인 논쟁이 길어져 합의점에 도달하지 못한다면, 팀 단위 토론을 진행하거나 기술 매니저에게 도움을 요청하자.

(5) 셀프 리뷰의 수단으로 코멘트를 활용해보자(리뷰 요청자 관점)

• 앞서 설명했듯이 코드리뷰는 리뷰어, 리뷰요청자 간의 커뮤니케이션이다.
• 리뷰어가 해당 PR의 맥략을 다 이해하면 좋겠지만, 새 기능 추가나 시스템 도입의 경우 쉽지 않다.
• 이 경우, 리뷰요청자는 리뷰어의 이해를 돕도록 자신의 코드에 설명 코멘트를 남겨보자.
• 아래 이미지는 새롭게 도입된, 테스트 코드 관련하여 남긴 셀프 코멘트이다.

• 혹은 전반적인 설계에 대한 설명이 필요하다면 별도 코멘트를 남겨도 된다.

(6) 피드백 사항이 없다면 칭찬합시다

• 코멘트할 사항이 없다면, 억지로 방안을 제시하기보다는 칭찬을 하자!
• 칭찬 피드백의 경우, 단순히 ‘잘했어요!’ 보다는 이유도 같이 붙여주는 게 더 좋다.

칭찬 코멘트 예시)

많은 고민을 한 흔적이 보이는 설계네요, GOOD!
예외처리를 적절히 해주셨네요!
이전에 비해 코드 퀄리티가 향상된 게 보여요 LGTM
코드가 직관적이라 이해하기 쉬웠어요 좋아요~

• 한 예시로 본인의 경우, 코멘트에 칭찬을 남길 때 짤과 이유를 같이 남기곤 한다.(아래 이미지는 주로 쓰는 짤)

• 좀 더 색다른 방식으로 칭찬 코멘트를 남기고 싶을 때 주로 쓰곤 한다.ㅎㅎ

(7) 코멘트별로 중요도를 표시해주세요(뱅크샐러드의 Pn 룰)

• 뱅크샐러드에서 쓰는 방식 중 하나인 Pn 룰이다.
• Pn 룰은 리뷰어가 각 코멘트별로 강조하고 싶은 정도를 표현하는 방식이다.
• 해당 방식은 우리 팀에서도 사용하고 있는데, 리뷰요청자가 코멘트의 중요도에 따라 수용할 수 있다는 장점이 있다.

중요도	설명
P1: 꼭 반영해주세요 (Request changes)	- 해당 PR이 중대한 오류를 발생할 수 있는 가능성이 있어 반드시 수정이 필요한 경우, P1 태그를 통해 리뷰 요청자에게 수정을 요청함.  - 리뷰 요청자는 p1 태그에 대해 리뷰어의 요청을 반영하거나, 반영할 수 없는 합리적인 의견을 통해 리뷰어를 설득할 수 있어야 함.
P2: 적극적으로 고려해주세요 (Request changes)	- 리뷰 요청자는 P2에 대해 수용하거나  - 만약 수용할 수 없는 상황이라면 적합한 의견을 들어 토론할 것을 권장함
P3: 웬만하면 반영해 주세요 (Comment)	- 리뷰요청자는 P3에 대해 수용하거나  - 만약 수용할 수 없는 상황이라면 반영할 수 없는 이유를 들어 설명하거나  - 다음에 반영할 계획을 명시적으로 표현할 것을 권장
P4: 반영해도 좋고 넘어가도 좋습니다 (Approve)	- 리뷰요청자는 P4에 대해서는 아무런 의견을 달지 않아도 됨.  - 해당 의견을 반영하는 게 좋을지 고민해 보는 정도면 충분함.
P5: 그냥 사소한 의견입니다 (Approve)	- 리뷰요청자는 P5에 대해 아무런 의견을 달지 않아도 됨.

(8) 개발자의 성향을 리뷰하지 마세요

• 코드의 성능이나 개선점이 아닌 개발자의 성향을 리뷰한다면 리뷰의 본질이 사라지게 된다.
• 한 예시로 ‘가독성’을 들 수 있는데, 리뷰요청자는 if ~ else문이 가독성이 좋다고 생각하지만 리뷰어는 삼항 연산자가 가독성이 좋다고 생각할 수 있다.

function getDay(dt) {
  if (isWeekend(dt)) return weekend;
  else  return weekday;
}

• 하지만 가독성은 주관적인 영역이므로, 성능상 큰 차이가 없다면 주관적인 부분에 대해선 코멘트를 지양하는 게 좋다.

나쁜 예시)

return isWeekend(date) ? weekend : weekday;로 작성하면 가독성이 높아집니다.

💡 이번 시간에는 좋은 리뷰 코멘트를 작성하는 방법에 대해 알아보았다.
먼저 코드 리뷰 또한 커뮤니케이션 이기에 예의를 지킬 것,
근거를 제시할 것, 방향성을 제시할 것 등등이 있었다.
또한 리뷰 요청자의 경우, 셀프 코멘트를 사용해 양질의 리뷰를 요청할 수도 있다.

오늘 제시한 내용들이 정답은 아니기에 각 팀의 상황에 따라 리뷰 문화를 만들어나가면 좋을 듯 하며,
다음 시간에는 리뷰 요청을 잘하는 방법도 한 번 알아보겠다.

참고 자료

• 오늘 작성한 내용은 아래 링크의 내용을 토대로 재구성하였습니다 🙂

1. https://tech.kakao.com/2022/03/17/2022-newkrew-onboarding-codereview/
2. https://www.bloter.net/news/articleView.html?idxno=21860
3. https://www.samsungsds.com/kr/insights/global_code_review.html
4. https://google.github.io/eng-practices/
5. https://blog.banksalad.com/tech/banksalad-code-review-culture/
6. https://www.theteams.kr/teams/859/post/64467