본인이 작성한 코드를 누군가에게 평가받는 것은 다소 부끄러울 수도 있고, 코드 리뷰를 받는 경험이 처음이라면, 더더욱 걱정이 될 수도 있습니다. 그럼에도 나의 코드가 충분히 검토된 상태로 배포까지 이루어지는 프로세스를 경험해보면서, 개인적으로는 충분한 피드백을 통해 성장하고 새로운 시각을 얻을 수 있으며, 팀 차원에서 코딩 스타일과 로직을 맞추어 가며, 회사 차원에서는 프로덕트 안정성이 확보되는 경험을 해보면서 코드 리뷰라는 것이 오히려 기다려지고, 안정감을 주는 부담없는 프로세스로 인식될 것이라 생각합니다.
이 글에서는 일레클의 웹프론트엔드 팀에서 정리한 코드 리뷰 프로세스와 Pull Request와 관련된 내용을 소개하고자 합니다. 이를 통해, 팀에서 코드 리뷰를 처음으로 도입하는 시점에서, 혹은 기존의 리뷰 방식을 변경하고자 하는 분들에게 제가 정리한 방식의 고민을 통해 더 나은 방식의 코드 리뷰가 이루어 질 수 있기를 기원합니다.
코드리뷰가 필요하신가요?
여느 스타트업 초기 단계에서 담당하고 있는 프로덕트(레포지토리)에 1인 팀으로 내가 개발하고 있는 코드를 누구도 검토해줄 수 없는 상황에서는 코드 리뷰라는 프로세스를 진행하기 어렵습니다. 이러한 상황에서는 코드 리뷰를 과감히 포기하고 구현에 집중하며 테스팅, 디버깅, 사후적인 오류 발견에 의존할 수 밖에 없습니다.
그러나 코드 리뷰가 가능해지는 인적, 업무적인 상황이 온다면, 반드시 코드 리뷰를 진행해야 한다고 생각합니다. 아래서 설명을 드리겠지만, 코드 리뷰를 진행하는 것은 그 프로세스 자체로서도 물론 필수적이지만, 진행하는 팀원들이 이에 대해 공감하고, 같은 방향을 바라보면서 맥락과 의도를 공유하여 더 나은 개발 문화를 만들고자 하는 것 그 자체가 더 중요하다고 생각합니다.
아래에서는 다음과 같은 순서를 통해 제가 코드 리뷰를 도입하기 위해 고민하고 정리했던 내용을 소개해드리고자 합니다. 내부적으로 논의하고 고민한 내용을 정리한 형태라 다소 딱딱할 수 있지만, 충분히 고민의 내용을 반영하였기에 코드 리뷰를 왜, 어떻게 진행해야 하는지에 대한 질문에 나름의 답이 되었으면 합니다.
특히 코드 리뷰는 단순하게 코드 리뷰를 요청하고 진행하는 형식이 중요한 것이 아니라, 리뷰 요청자와 리뷰어, 그리고 팀 차원에서도 매우 중요하고 핵심적인 업무라는 점을 인지하는 것이 더더욱 중요하다는 관점하에 레퍼런스를 참고하여 추가적인 생각을 녹여 정리해보았습니다.
- 코드리뷰란?
- Why? 코드 리뷰의 목적: 무엇을 위해 코드 리뷰를 진행하는가?
- When? 코드 리뷰는 언제까지 진행해야 하는 것인가?
- How? 코드리뷰는 어떻게 제출하는가?
- What? 코드리뷰 시 무엇을 확인해야 하는가? 리뷰 시 확인해야 할 디테일(리뷰어)
- 레퍼런스
코드리뷰란?
- 코드리뷰란, 한 명 또는 여러 명의 개발자가 코드의 내용을 점검(examining)하고, 피드백을 전달하여, 작성자가 이를 다시 반영하는 과정으로 코드에 대한 책임이 그 코드를 만든 사람 혼자에게 있지 않고 우리 모두에게 있다는 문화를 만드는 데에 그 의의가 있다고 할 수 있다. ⇒ ‘책임자를 추궁하지 않는 문화’의 정착
- 주로 Github의 Pull Request 기능을 이용하여 진행한다.
- 코드 리뷰라는 프로세스를 진행하며 개발 업무 이외의 추가적인 리소스를 투입해야 하지만, 코드 리뷰를 요청하고, 작성하는 과정, 그리고 피드백을 제공하는 과정을 통해 들이는 리소스 이상의 장점을 얻어갈 수 있을 것을 기대할 수 있다.
- Pull Request의 형태로 진행하는 코드 리뷰는 기본적으로 commit, file diff를 통해 개발자의 인지적인 역량에 의존하고 있다. 피드백을 제공하는 개발자가 인지하지 못하는 오류는 코드 리뷰를 통해서도 발견되지 않을 것이다. 다만, 코드 작성자와 다른 최소 1인의 리뷰를 통해 발견되지 않는 오류를 찾아 에러 가능성을 줄이고, 코드 퀄리티와 팀으로서의 코드 일관성을 높이는 과정을 통해 인지적 역량(개발자로서의 역량)도 상호적으로 높일 수 있을 것이라 기대할 수 있다.
- 그럼에도 피드백을 제공하는 형태의 코드 리뷰는 한계가 있고 모든 가능한 side effect를 오류 없이 발견하는 것은 불가능하기 때문에, 기술적인 개선을 통해 오류 발견 가능성을 제고할 수 있음을 항상 염두에 두어야 한다. 예를 들어 CI/CD 자동화를 통해 빌드가 정상적으로 진행되는지? 코드 분석 툴을 이용하여 deprecated코드를 확인할 수 있는지? Test를 통해 구현하고 있는 기능에 대하여 충분히 테스팅할 수 있는지? 등 기계적 자동화를 통해 인지적으로 놓치는 부분을 줄일 수 있다. 다만, 모든 가능한 기술적 개선이 현 시점에서 필수적으로 선제적으로 적용되는 것은 비현실적이다.
⇒ 항상 현재 팀 구성과 상황에 맞는 Must와, 현재는 직접적으로 도입할 수 없지만, 언젠가 보충이 필요하고 도입할 수 있는, 지향할 수 있는 Should, 도입할 수 있는 Can을 함께 고려하자.
일레클 웹프론트엔드팀 코드 리뷰에서의 Must, Should, Can
- Must: 코드리뷰의 정의, 목적, 일정, 제출, 검토에 대한 정리 및 공유, 코드리뷰에서 하지 않아야 할 것에 대한 공유, Github Pull Request Template을 이용한 체크리스트 및 검토 리스트 자동화,
- Should: Test code 작성, gerrit 같은 코드 리뷰 시스템, 인건비를 아끼는 코드 리뷰 관련 자동화 도입
- Can: 오프라인 팀 코드 리뷰
Why? 코드 리뷰의 목적: 무엇을 위해 코드 리뷰를 진행하는가?
코드 퀄리티와 일관성 유지
- 중복 코드를 방지하고 모듈의 재사용성 증대
- 오타 발견, 일관된 코딩 스타일, 일관된 아키텍처를 유지
팀 내 개발 역량 상향 평준화, 비즈니스 로직에 대한 이해 맞추기
- 서비스의 기술적인 히스토리 전달, 현재의 구현 형태에 대해 공유, 습득
- 개인 간의 격차를 해소, 이해 수준의 상향 평준화
선제적인 문제점 발견 및 대응
- 문제를 해결할 수 있는 새로운 관점 발견(다른 해결 방법에 대한 의견 제시)
- 예상되는 잠재적인 장애/버그를 배포 전에 발견 서비스 운영 비용 절약 기대
긍정적인 리뷰를 통한 상호 성장
- 좋은 코드에 대한 긍정적인 피드백
- 기술적인 지식, 노하우 공유
- 위 목적을 달성하기 위해서 다른 대안이나 보충적인 수단이 없을까? 를 고민해 볼 수 있다.
When? 코드 리뷰는 언제까지 진행해야 하는 것인가?
언제
- 기본적으로 배포를 위한 dev 혹은 master브랜치에 머지를 하기 위한 pull request를 생각하기 쉽지만, 코드 리뷰가 되는 코드의 양을 줄이고, 리뷰를 원활하게 하기 위해 작은 단위의 pr 형태를 지향합니다.
- dev혹은 master브랜치에 배포를 하는 경우가 아니라면 본인 혹은 팀이 맡은 feature단위의 브랜치를 설정하고, 해당 feature 브랜치로 잘게 쪼갠 단위의 작업에 대해 리뷰를 요청할 수 있도록 합니다.
- 브랜치 관리 전략에 대한 팀내 논의/결정과 병행되어야 함.
언제까지
- 구글에서는 간단한 리뷰는 제출된 후 1시간 내로, 규모가 큰 리뷰는 제출된 후 4~5시간 이내로 완료해야 하는 rule이 있다. 개발팀의 규모와 진행 중인 프로젝트의 규모에 따라 다르겠지만, 최대한 PR을 가볍게 작성한다는 가정 하에 가능하면 빠른 시점에 코드 리뷰가 이루어 지는 것이 바람직하다.
- 코드 리뷰의 데드라인은 리뷰를 제출하는 사람이 가장 잘 판단할 수 있다. 본인이 진행중인 개발 프로세스에서 해당 코드가 리뷰되어야 하는 시점의 중요성이 어느정도인지, 스프린트 상 어느 중요도와 우선 순위를 가지고 있는지 판단하여 리뷰 데드라인을 설정할 수 있다.
- 즉. 가능하면 빠른 시점에 코드 리뷰를 진행하여 상호 리뷰로 인한 디펜던시를 줄일 수 있지만, 모든 리뷰가 시급한 검토를 요하지는 않기에, 리뷰 요청자는 본인의 판단 하에 리뷰 우선순위/데드라인을 설정하도록 한다.
- 리뷰 검토자는 놓친 코드리뷰가 존재하는 지 최소한 매일 업무 시작 시 반드시 확인하도록 하며, 요청자의 리뷰 우선순위/데드라인을 확인하고, 해당 데드라인을 지키지 못하는 경우에는 코멘트를 통해 사유를 공유하도록 한다.
리뷰 우선순위/데드라인 설정 - 라벨을 통해 명시적으로 표현할 수 있도록 한다.
- 리뷰 우선순위 판단을 돕는 D-n 룰(뱅크샐러드)을 통해 적용 가능한 방식의 데드라인 설정 방식을 정했습니다.
웹 프론트 팀의 리뷰 우선순위 라벨 생성
- ASAP : 즉시 리뷰가 필요합니다. 버그, 에러로 인해 빠른 배포가 필요합니다. (0시간 리뷰)
- D-0 : 가능하면 당일 빠른 리뷰가 필요합니다. 작업 디펜던시가 존재하여 먼저 리뷰가 요구됩니다.(1시간~4시간 이내 리뷰)
- D-x : 작업 디펜던시는 없으며, 적당한 시점에 리뷰가 완료되면 됩니다. (1~3일 리뷰)
(설명) D-x의 x에 숫자를 명시하는 것이 아니며, 코드 리뷰는 가급적 빨리 이루어지는 것이 바람직하다는 전제 하에, 리뷰어의 부담이 없는 형태의 요청입니다.
How? 코드리뷰는 어떻게 제출하는가?
다음의 주요 원칙, 세부적인 목표를 바탕으로 Github에 Pull Request Template을 작성하도록 합니다.
- PR은 빠르고 가볍게 작성한다.
- 변화를 작게 유지하자(라인)
- 리뷰는 자주 짧은 세션으로 진행하자(라인)
- 리뷰를 위해 최대한 빨리 PR을 보내자(라인)
- 리뷰 코드의 양(코드 라인)을 줄인다. — 200줄 이하, 브랜치 관리 - 의미있는 PR을 만들기에 충분한 정보를 제공한다.(라인)
- 맥락의 충분한 공유
- 저 문맥(Low Context) 커뮤니케이션을 지향하는 문화(뱅크샐러드)
⇒ 리뷰어가 사전 지식이 없는 상태에서 리뷰에 참여한다는 가정으로 모든 문맥을 제공
⇒ 맥락 제공을 위한 template(Product Spec(notion/asana/slack), Tech Spec(if any), Figma(If any))
⇒ 기타 관련 문서 - 추가/수정된 기능에 대해 명확하게 설명한다.
- 변경된 파일, 함수에 대한 rough한 스케치
- 기능은 명시하여 파악할 수 있도록 하되, 실제 코드를 확인해야 하므로 연관된 코드에 대한 설명은 가볍게 한다. - 구현 체크 요청
- 실제 기능 테스팅이 필요하다고 판단되는 경우 경우 별도로 요청한다. - 리뷰시 중점적으로 확인 해주어야 할 부분 요청
- 참고한 레퍼런스(stackoverflow, official docs)
- 배포(자동/수동)
- 구축된 파이프라인 별 배포 자동화/수동 배포가 수반되는 변경 내용일 경우, 배포에 대한 요청과 담당을 명확히 요청/제시한다.
- ex) dev/main, master에 배포되는 경우 반드시 배포가능한 상태인지 확인
⇒ 반복되고 명시적인 요청 내용은 tag로 만들어 쉽게 인식할 수 있도록 하는 것이 목표.
ex) 깐깐한 리뷰, 배포 요청 등을 템플릿에 녹여낸다.
(이를 바탕을 pr template을 생성하였습니다.)
What? 코드리뷰 시 무엇을 확인해야 하는가? 리뷰 시 확인해야 할 디테일(리뷰어)
리뷰시 어떠한 것을 확인해야 하는가? 코드리뷰의-진짜-목적은-따로있다/ 참고
- 기능의 정상 동작 여부
- 리뷰 요청에 작성된 기능 변경/추가가 정상적으로 작동하는지
- 기존 기능이 문제 없이 동작하는지 - 버그의 조기 발견
- 예상치 못한 버그 가능성을 인지할 수 있는지
- 최대한 빠르게 버그를 발견할수록 해결 비용이 줄어든다. - 가독성과 유지보수 편의성
- 팀 차원의 코드 관리에서 중요하나, 논쟁의 여지가 있음.
- “주관적인 견해로 옳고 그름을 따지는 비생산적 논쟁으로 변질될 수 있으므로 가급적 기준을 정하고 해당 기준을 기반으로 검토하는 것이 좋습니다. 예를 들어, 들여쓰기(indent)의 크기나, 코드 한 줄의 최대 길이, 메소드 호출의 깊이(depth )등의 표준을 정해두면 좀 더 객관적인 기준으로 코드리뷰를 수행할 수 있습니다.”
- 자동화와 lint rule을 추가하는 방향으로 불필요한 소모적 논쟁을 줄이기. - 개발 표준(CONVENTION)의 준수 여부, 코딩 스타일 ( Indent, Convention )
- 상황에 맞게 최소한의 기본적인 표준을 정하고, 하나씩 세부적으로 추가해나간다.
- 정해지지 않은 컨벤션에 대해서 서로 다른 의견을 가지고 있는 경우, 기본적으로 비즈니스 로직이 이상해지지 않는 선에서 작성자의 convention을 따르며, 이후 팀 토크에서 해당 부분에 대한 컨벤션을 정하고(합의), 컨벤션을 적용해나간다. - 테스트 코드의 작성 여부
- 팀에서 테스트 코드의 중요도에 대한 합의, 커버리지와 작성 방식에 대한 합의 필요 - 재사용 가능한 모듈의 중복 개발, 배울만한 점은 없는지, 코드 자체 개선 가능성이 있는지 제안
리뷰시 커뮤니케이션 비용을 줄이기 위해 요청의 형태를 명확하게 제시한다.
- 리뷰시 다음과 같은 태그를 남겨 소통에서 오해가 없도록 합니다. 참고:커뮤니케이션 비용을 줄이기 위한 Pn 룰(뱅크샐러드)
- [Major-Must]: 에러, 기능 미구현, 오동작이 포함되어 있습니다. 반드시 반영해주세요.
- [Major-Discussion]: 에러, 기능 미구현, 오동작이 포함되어 있습니다. 논의가 필요합니다. 의견을 듣고 싶습니다.
- [Major-Request]: 에러, 기능 미구현, 오동작이 포함되어 있습니다. 다음 형태로/다음 기능을 반영해주실 것을 요청합니다.
- [Recommend-Must]: 에러, 기능 미구현, 오동작은 없습니다. 다음 형태의 개선을 추천하고 반영해주세요.
- [Recommend-Request]: 에러, 기능 미구현, 오동작은 없습니다. 다음 형태의 개선을 추천합니다만, 반영하지 않아도 좋고 제안해봅니다
- [Question/Check]: 질문이 있습니다/확인하기 위한 코멘트입니다.
- [Ok]: 문제 없습니다. 확인하였습니다.
- [Good]: (어떠한 부분이) 좋습니다
- (OK인지, GOOD인지 고민을 통하여 긍정적인 피드백을 유도한다.)
참고 url
- 라인(큰 방향에 대한 설명)
- 뱅크샐러드(세부적인 실제 적용 케이스가 도움이 됨, 많이 참고함)
- 우리테크
- 실리콘밸리-구글 개발자의 생생후기(생각보다 느슨한데, 노하우를 참고했음)
- 삼성sds에서 정리한 구글, ms, 네카라쿠배의 코드리뷰(정리)
- https://blog.logi-spot.com/코드리뷰의-진짜-목적은-따로있다/(좋은 예시와 좋은 설명)
리뷰 룰 회고
위와 같이 코드 리뷰 룰을 정리하고 3개월 정도가 지난 시점에서, 리뷰 룰을 얼마나 잘 준수하고 있는지, 스스로 평가를 해보자면..
- 위 내용을 공유하여 정리한 github pr template은 효율적으로 사용하고 있습니다.
- D-x 룰을 리뷰 요청자가 명시하는 과정이 실제로 매우 도움이 됩니다. 리뷰 자체의 우선순위는 높게 가져가는 것을 기본으로 하되, D-x를 통해 시급한 리뷰나 느린 리뷰에 대해 서로 추가적인 커뮤니케이션 없이 합의가 가능한 것이죠
- 다만 리뷰어가 코멘트의 의도를 명확하게 하기 위해 이용하고자 했던 태그를 일상적으로 활용하지는 못하게 되었는데, 이는 실제 이 태그를 사용하는 목적이 무엇인가로 변명(?)을 할 수 있는데요(…) 코멘트를 통해 태그에 준하는 의도를 충분히 설명하고 있기에 미스커뮤니케이션이 발생하지 않고 있습니다. 그렇지만 초기에 코드 리뷰를 도입하거나, 팀원의 수가 많거나, 미스커뮤니케이션의 경험이 있었다면 일단 코멘트 의도 태그를 적극적으로 사용하는 것이 더 나을 듯 합니다.
- 코드 리뷰를 더 자주하기 위해서는 명확한 브랜치 관리가 필요합니다. 이에 따라 브랜치 룰을 정립했습니다.
맺으며
코드 리뷰를 도입하는데 있어 무엇보다도 중요한 것은 내부에서 위와 같은 형태의 자체 코드 리뷰 룰을 마련하기 위한 프로세스 그 자체라고 생각합니다. 무작정 템플릿을 가져오고, 정해지지 않은 방식으로 리뷰를 진행하기에 앞서 현재 팀의 상황을 명확히 인식하고, 그에 맞는 프로세스를 함께 논의하는 과정을 통해 현재 우리 팀에게 가장 맞는 형태의 코드 리뷰 룰을 정하는 것이 필요한 것이죠. 자체 코드 리뷰 룰을 도입하는 시점에 고민하고 계시는 분에게, 제 글이많은 도움이 되었길 바랍니다.
