Tech
지속가능한 코드리뷰 문화를 만드는 여정
2023. 05. 11
안녕하세요, 화해 백엔드 플랫폼 이현재입니다. 지난번에 작성한 「우리는 개발문화에 진심입니다」에서 코드리뷰를 약속드려 이번 주제로 준비했어요. 코드리뷰, 더 나아가 개발조직 문화를 고민하는 분들께 도움이 되면 좋겠네요. 지속가능한 코드리뷰 문화를 만드는 여정
이 글은 코드리뷰 목적부터 시작하여 리뷰어 선정 변천 과정, 코드리뷰 비용을 줄이면서 효과적으로 리뷰하는 방법 순서로 이루어졌습니다. 화해팀에서 지속 가능한 코드리뷰 문화를 만들기까지 다양한 방식으로 접근했던 방법을 집대성하였어요. 개발 조직의 업무 능력을 향상하면서 코드 품질을 관리하는 방법을 함께 살펴볼까요?
코드리뷰 목적
함께 개발하려면 코드리뷰는 필수입니다. 코드리뷰란, 개발자가 작성한 코드를 다른 개발자들이 검토/분석하는 과정을 일컫죠. 코드리뷰 목적은 크게 세 가지로 나눠볼 수 있습니다.
서비스 안정성 보장
다른 개발자가 코드를 검토하면서 잠재적인 오류를 발견하고, 배포 전에 개선하여 서비스 안정성을 높여요. 코드를 검토하며 미리 살펴보았기에 문제 발생 시 오너쉽을 가진 개발자가 아니더라도 주변 개발자가 빠르게 대응 가능해요.
업무 효율 증대
코드리뷰 과정 중에 설계나 코딩 스타일이 정립되며, 사람마다 다른 개발 방식을 하나로 맞추어 나가요. 그 과정에서 코드 가독성 및 유지보수성이 개선돼요.
지식 공유 및 코드 품질 향상
코드를 검토하는 과정에서 지식 공유가 이루어져요. 서로 다른 시각과 경험을 공유하며, 새로운 기술과 도구를 학습하고 개발 실력이 향상됩니다. 코드리뷰는 개발자끼리 상호 교류하는 과정이며, 협업을 바탕으로 개발문화를 발전시키는 한 가지 방법이에요.
코드리뷰 문화를 도와주는 리뷰 마니또
다양한 이점을 지닌 코드리뷰를 개발문화에 도입하고자 마음을 잡았더라도 몇 가지 잡음이 발생하기 마련인데요. 그중 하나가 바로 리뷰어 선정 방식이에요. 보통 코드리뷰를 개발 프로세스로 도입하게 되면 리뷰어 n명이 PR을 승인해야 배포가 가능하죠? 리뷰어를 어떤 방식으로 선정하는지에 따라 코드리뷰 효율이 달라져요. 먼저 구성원 전체를 리뷰어로 지정한다는 가정으로 접근해 보죠. 결론부터 이야기하자면 모든 PR에 전체 인원이 리뷰어로 지정될 경우 리뷰가 원하는 시점에 이루어질 가능성은 낮습니다. 이는 간단하게 증명 가능한데요.
위급 상황에서 다른 이에게 119나 112에 신고를 부탁할 때 특정인을 지목하라는 이야기를 들어보셨을 거예요. 이와 관련된 사례로 60년을 거슬러 올라 키티 제노비스 사건을 찾을 수 있습니다. 뉴욕에 거주하는 여성이 강도에게 살해당한 사건이죠. 범인과 단둘이 30분을 넘게 실랑이를 하는 모습을 목격한 38명 모두 그녀를 돕거나 경찰에 신고하지 않았다는 뉴욕타임스 보도로 화제가 되었습니다. 이 사건을 계기로 주위에 사람이 많을수록 돕지 않는 현상을 일컫는 방관자 효과는 피해자 이름을 따 ‘제노비스 신드롬’으로도 불러요.
뉴욕타임스 보도가 사건의 사실과 일치하지 않는다는 이야기를 뒤로 미뤄두더라도 방관자 효과는 여러 매체에서 증명한 이론이에요. 이 이론을 바탕으로 살펴보면 다수를 리뷰어로 지정하는 건 옳지 못하다는 결론이 도출되죠.
그럼 이제 우리가 고민해야 할 건 한 가지예요. 리뷰어를 어떻게 지정하고 배분할지 결정해야 하는 것인데요. 몇몇 기업은 시니어나 PR 올린 개발자보다 연차가 많은 사람을 리뷰어로 지정하는데, 옳은 방식이라 여기기에는 다소 무리가 있어요. 특정인에게 부담을 가중한다는 건 언제나 많은 문제를 야기하니까요. 화해 백엔드 플랫폼은 어떻게 해결하였을까요? 저희는 ‘리뷰 마니또’라는 코드리뷰어 선정 방식을 사용합니다.
리뷰 마니또 그 변천사
리뷰 마니또는 리뷰어 지정 고민을 줄이고자 백엔드 플랫폼에서 도입한 리뷰어 지정 방식을 말해요. 상호 간 리뷰어를 배정하는 건 구성원이 짝수일 때만 가능한 방법이라 꼬리물기 방식으로 선정하는데, 한 달에 한 번씩 스케쥴러로 마니또를 지정해요. 리뷰를 요청한 사람은 마니또가 리뷰를 수월히 진행할 수 있도록 지원을 아끼지 않는다고 문서로 명시해 두었어요. 문서로 명시해야 신규 입사자가 생기더라도 빠르게 개발 문화를 받아들일 수 있어요. 다음은 화해 백엔드 플랫폼의 코드리뷰 문서 일부예요.
리뷰 마니또
- 백엔드 플랫폼 모든 구성원은 본인이 속한 도메인 인원 1명에게 마니또로 지정된다.
- 마니또로 지정된 사람은 요청받은 테크스펙과 PR 리뷰에 필수 참여한다.
- 마니또는 매월 첫째 주에 봇으로 선정하며 1달간 유지한다.
- 리뷰 요청자는 리뷰를 수월히 진행할 수 있도록 콘텍스트 설명과 질의응답 등 지원을 아끼지 않는다.
- 동일한 사람이 리뷰어로 지정되지 않도록 리뷰 마니또는 랜덤으로 선정한다.
1년 전만 하더라도 도메인이 다른 개발자 1인을 마니또로 지정하였는데요. 당시에는 평소에 엮일 가능성이 적은 타 도메인 코드를 리뷰하면 서비스 전체를 이해하는데 도움 되리라 기대하였어요. 일정 부분은 분명 그 기대를 충족하였지만, 그로 인한 문제점도 드러났는데요. 테크스펙 문서를 작성할 때 타 도메인 개발자들도 콘텍스트를 이해할 수 있도록 다소 장황하게 적어야 했어요. 개발 시작에 앞서 테크스펙을 작성하는 목적은 설계 논의를 빠르게 진행하기 위함이었으나 취지와는 조금 다르게 동작하였죠. 리뷰어 또한 전후 맥락을 자세히 모르다 보니 콘텍스트를 파악하기 위해 많은 시간을 할애해야만 했어요. 많은 시간이 필요한 만큼 간혹 리뷰 품질이 떨어지는 상황도 발생했습니다.
같은 도메인에서도 다양한 업무가 동시에 진행되는 만큼 업무 퀄리티를 높이기 위해 타 도메인과 싱크를 맞추기보다 지금과 같은 방식으로 변경했어요. 동일한 도메인으로 리뷰 마니또를 한정 지으면서 본인이 소속된 도메인 이해도가 더 높아지는 장점도 얻었어요. 기존 리뷰 마니또 선정 방식도 분명 순기능이 존재했지만, 도메인 간 교류는 매주 금요일에 진행하는 밋업이나 랜덤 티타임처럼 다른 방식으로 접근하여 해소하는 중입니다.
물론 필요에 따라 도메인 리더와 연관된 분들께 추가로 코드리뷰를 요청드리기도 하구요! 도메인 혹은 목적 조직마다 특색에 맞게 다듬어서 적용하고 있어요.
코드리뷰를 돕는 또 다른 컨벤션,
리뷰 코멘트 템플릿 도입
리뷰어가 남긴 메시지 의도를 명확히 파악하는 건 힘든 일이에요. 사람마다 표현 방식이 다르기에 문맥만으로 그 의도를 명확하게 이해하기란 요원하니까요. 게다가 납득이 가는 피드백은 큰 고민 없이 바로 반영하더라도 모든 코멘트가 그런 건 아니죠. 경중에 따라 단순한 참고 의견일 수도 있어요. 리뷰 전체로 보면 Approve, Comment, Change Request라는 선택지가 존재해도 세 가지만으로는 부족해요.
보다 효과적인 코드리뷰를 고민하던 중, 한 분께서 클라우드 컴퓨팅 기업인 Netlify 블로그 글을 하나 공유해 주셨어요. Netlify에서 Feedback Ladder라고 부르는 코드리뷰 방법론을 소개한 글인데요. Feedback Ladder는 리뷰를 남길 때 다섯 가지로 구분된 말머리로 코멘트를 시작하는 걸 말해요.
- Mountain: Blocking and requires immediate action
- Boulder: Blocking
- Pebble: None-blocking but requires future action
- Sand: Non-blocking but requires future consideration
- Dust: Non-blocking, “take it or leave it”
이처럼 코드리뷰 시 코멘트 중요도를 측정 가능한 레벨로 표기하면 커뮤니케이션 비용이 줄어들어요. 리뷰받는 사람에게 코멘트를 남긴 의도가 정확하게 전달되거든요. 리뷰 요청자는 중요도에 따라 업무 우선순위를 정해 처리가 가능하고, 자연스레 생산성 향상으로 이어져요. 화해팀은 이 방법론을 바탕으로 조직 특성에 맞추어 다음과 같이 리뷰 코멘트 템플릿을 정의하여 사용하고 있어요.
화해 백엔드 플랫폼, 코드리뷰 템플릿
[L0-리뷰불가]
- PR Description, 테크 스펙 등 어떤 작업을 했는지 충분한 설명이 없는 경우
- 변경 작업이 너무 커서 리뷰가 어려운 경우
- 설계가 잘못되어 전체적으로 재작업이 필요하다고 판단해 리뷰를 진행할 수 없는 경우
[L1-변경요청]
- 기능 결함, 심각한 퀄리티 저하, 팀 컨벤션 위반 등 반드시 머지 전에 변경이 필요한 경우
[L2-변경협의]
- 가급적 머지 전에 변경되었으면 좋겠지만, 배포 후 후속작업으로 바로 진행이 된다면 괜찮다고 생각하는 경우
- 작성자가 의견에 동의하지 않는다면 토론 필요
[L3-중요질문]
- 궁금증이 해소되어야 정확한 리뷰/피드백이 가능하다고 판단하는 경우
[L4-변경제안]
- 제시한 방안이 더 좋다고 생각하지만 작성자 판단에 맡겨도 무관한 경우
[L5-참고의견]
- 더 좋은지는 모르겠으나 다른 방법 제시 혹은 참고할만한 내용인 경우
꿀팁, 리뷰 코멘트 템플릿 사용 방법
리뷰 코멘트 템플릿을 하나하나 매번 손으로 직접 입력하기는 다소 번거로워요. 다행스럽게도 GitHub는 반복적인 내용을 등록하여 사용할 수 있는데요. GitHub 설정을 보면 Saved replies라는 메뉴가 보이실 거예요. 해당 메뉴에서 리뷰 코멘트 템플릿을 지정하면 단축키만으로도 편하게 사용 가능해요.
리뷰 요청자는 무엇을 챙겨야 할까요?
코드에 주석으로 설명이 필요한 부분이 아니라면 대개 코드만 작성되어 있기 마련이에요. 분명 변수와 메서드, 클래스가 가진 이름을 통해 코드가 만들어진 의도를 담지만, 표면적인 내용일 뿐이에요. 여러 방식 중에 어째서 이와 같은 방식을 채택했는지, 혹은 코드를 실행해 보며 테스트했던 결과물은 코드에 담기지 않아요. 그렇기에 리뷰를 요청한 사람이 미리 다른 개발자가 궁금해할 법한 내용을 코멘트로 추가해 두면 코드리뷰 비용을 줄일 수 있어요.
코드리뷰 비용을 줄이는 다양한 도구들
코드리뷰를 무턱대고 도입하면 예상보다 리소스가 많이 필요하다고 느낄 수 있어요. 이에 화해 개발팀에서는 비용을 줄이면서 효과적인 코드리뷰를 진행하고자 다양한 도구를 도입어요. 하나씩 가볍게 소개드릴게요.
코드리뷰 시작은 개발 설계부터, 테크스펙
테크스펙은 개발하기 전에 작성하는 설계 문서예요. 아키텍처나 인터페이스, 데이터베이스 구조, 더 나아가 테스트 계획 등을 기술하는 문서죠. 테크스펙을 작성하는 이유를 간단하게 정리해 볼게요.
- 명확한 목표 설정
문서로 정리하면서 개발 목표와 방향성을 명확히 이해하게 돼요. 개발 중에 생기는 혼란과 오해를 방지해요. - 요구사항 파악
테크스펙은 만들어야 하는 기능 명세를 정리해요. 시간이 흐르더라도 다른 개발자가 언제든 제품 요구사항을 이해하고 파악할 수 있어요. - 설계 구체화
필요에 따라 설계 및 아키텍처를 기술해요. 향후 유지보수나 확장을 용이하게 하기 위한 설계를 구체화하여 공유하고, 더 나은 아이디어를 동료로부터 얻어요. - 팀원 간 의사소통
개발에 필요한 정보가 한 곳에 모여있기에 협업 시 효과적으로 업무가 가능해요. - 개발 비용 절약
테크스펙 리뷰를 통해 사전에 문제를 예방하며, 개발 도중 발생할 수 있는 이슈도 미리 대응해요.
파이썬 정적 코드 분석 도구, Pylint
Pylint는 파이썬 코드를 검사하고 문제점을 찾아주는 라이브러리예요. 파이썬 코드의 가독성, 유지보수성, 일관성 등을 평가하여 코드 품질을 향상하는 데 도움을 줘요. Pylint는 코드 스타일, 변수명 규칙, 오류 및 예외 처리, 코드 복잡도 등 다양한 측면에서 코드를 분석하여 피드백을 제공하므로 개발자들이 놓치기 쉬운 코드의 문제점을 사전에 찾아내어 더욱 안정적이고 견고한 코드를 작성할 수 있도록 도와줘요.
파이썬 코드 포매터, Black
Black을 도입하기 전에도 PEP8을 준수하는 방식으로 코드 포맷을 맞췄어요. 다만 각자 문서를 읽고 ‘알아서’ 준수하는 방식으로 작업이 이루어졌어요. 이를 보완하고자 파이썬 코딩 스타일 컨벤션으로 정의한 규칙 중 일부를 자동화하기 위해 도입하였어요.
Black을 사용하면 띄어쓰기, 개행, 콤마, 따옴표 등 코드 포맷팅을 신경 쓰지 않아도 자동으로 맞춰줘요. 자동화 덕분에 코드리뷰 우선순위가 낮은 코드 포맷 컨벤션에 시간을 할애하지 않아도 되죠. 또한 Black이 일관된 형태로 코드 스타일로 맞추면서 가독성도 높아졌어요. 업무 시 코드 포맷팅보다 중요한 개발 설계나 비즈니스 로직에 더 집중하도록 도와주는 도구예요.
파이썬 import 관리 도구, isort
Pycharm도 Optimize import 기능을 제공하지만 PEP8에 문서화되지 않은 import 그룹 내 정렬은 지원하지 않아요. 오로지 세 가지 조건으로만 import를 관리해요.
- Standard library imports
- Related third party imports
- Local application/library specific imports
isort는 import를 사전 순으로 정렬하고 조건 별로 그룹화하는 도구예요. 컨벤션을 지킨 import는 가독성과 유지보수성을 향상시켜요. Black과 동일하게 cli 기반으로 동작 가능하며, IDE에 따라 코드 변경 시 자동 실행하도록 설정할 수 있어요.
주요 로직 안정성을 높이는 테스트 코드
화해팀은 로직이 변경될 때 관련 테스트 코드가 없다면 코드를 병합할 수 없어요. 변경된 코드에 대해 테스트 코드를 작성하는 덕분에 사이드 이펙트를 방지할 수 있어요. 통합 테스트는 물론이고 주요 로직은 유닛 테스트를 통해 비즈니스 로직과 일치하는지 확인하는 작업을 거쳐요.
실시간 피드백이 필요할 때는 페어프로그래밍
코드리뷰는 비동기를 기본으로 하지만, 경우에 따라 실시간 논의가 필요한 상황도 발생해요. 빠르게 논의를 거쳐야 하는 상황에서는 페어프로그래밍을 진행해요. 재택근무를 하다 보니 Code With Me나 게더타운, 슬랙 허들을 추가로 사용해요. 필요하다면 사무실에 모이기도 해요.
코드리뷰를 도입한 목적이 이루어졌나요?
코드리뷰를 지속적으로 유지하면서 상당 부분 코드 품질이 개선되었어요. 앞서 이야기드렸듯 사전에 버그를 예방한 적도 많아요. 최근에 제가 만들었던 코드도 다른 분께서 남긴 리뷰 덕분에 버그를 고치기도 했고. 반대로 제가 올린 PR을 본 다른 분께서 좋은 개발 방식을 배웠다며 이야기를 주신 적도 있어요. 다른 분께서 작성한 좋은 코드를 보며 저도 많이 배우고 있어요.
코드리뷰가 중요한 건 서로가 동일한 콘텍스트를 유지하는 효과적인 방식이기 때문이에요. 코드리뷰를 하지 않더라도 서비스를 만드는 데 커다란 걸림돌이 되지는 않지만, 담보로 잡아야 할 위험부담이 커요. 초가삼간을 태우기 전에 예방하는 게 더 적은 비용을 들이는 방법이니까요. 코드리뷰는 팀 내 협업과 더불어 서비스 성장의 주춧돌 중 하나예요. 의견 합치가 이루어낸 시너지는 굳이 더 말하지 않더라도 다들 아시라 믿어 의심치 않습니다.
맺음말, 코드리뷰에 빠질 수 없는 소프트 스킬 중요성
다양한 개발 커뮤니티에서 개발자들을 만나다 보면 소프트스킬이 가진 중요성을 간과한 사람들을 종종 봅니다. 하드스킬에 해당되는 ‘프로그래밍 실력만 좋으면 충분하지 않은가?’라고 반문하는 개발자들도 보고요. 개발자뿐만 아니라 자신이 지닌 깜냥을 바탕으로 가치를 만드는 프로라면 하드 스킬은 당연한 겁니다. 주어진 과업을 수행하지 못하는 사람을 고용할 이유는 없거든요. 삶과 밀접하게 관련된 영역이라 경제학을 배우지 않더라도 누구나 아는 사실이에요.
코드리뷰 또한 상호작용이기에 소프트 스킬이 중요해요. 코드리뷰를 주제로 작성된 다른 글을 살펴보면 소프트 스킬 중심으로 내용을 풀어나가는 걸 쉽게 찾아볼 수 있어요. 소프트 스킬로 할 이야기가 많으니 다음 주제로 찾아뵐게요!
참고자료
- Feedback Ladders: The Code Review System We Follow at Netlify
- https://github.com/pylint-dev/pylint
- https://github.com/psf/black
- https://github.com/pycqa/isort/
이 콘텐츠가 마음에 드셨다면 다른 글도 확인해보세요!
