• 한글판: 좋아보여

Part 1. 코드 리뷰의 기초 지식

Chapter 1. 코드 리뷰의 중요성

• 다음 질문
  • 현재 우리의 코드 리뷰 프로세스는 유용한가?
  • 우리의 코드 리뷰가 너무 오래 걸리는 것은 아닌가?
  • 누군가 혼자서 리뷰의 짐을 떠안고 있는 것은 아닌가?
  • 유달리 복잡하고 힘든 코드 리뷰 후에도 여전히 서로를 좋아하는가?
  • 제안이나 건설적인 비판을 작성하는 방법에 대해 알고 있는가?
  • 피드백을 효과적으로 처리하는 방법을 알고 있는가?
  • 우리의 코드 리뷰 프로세스가 목적대로 진행되고 있는가?
  • 목적에 대해 모두의 의견이 일치하는가?
  • 자동화의 이점을 잘 활용하고 있는가?
  • 코드 리뷰 프로세스에서 각자의 역할과 기대사항을 잘 알고 있는가?
  • 코드 리뷰가 소프트웨어 개발 프로세스에 가져오는 가치를 모두 이해하고 있는가?
  • 코드 리뷰가 중요한 이유를 설명하고 비지니스 가치와도 연결할 수 있는가?
  • 팀의 리뷰 프로세스를 좋아한다고 자신 있게 말할 수 있는가?

1.1. 대상 독자

• 소프트웨어 개발에 막 입문한 개발자
• 소프트웨어 개발팀에 속해 있으면서 코드 리뷰의 중요성을 알고 있고, 팀의 프로세스를 만드는 데 도움이 필요한 개발자
• 팀의 코드 리뷰 프로세스를 개선할 수 있다고 생각하는 개발자
• 어려운 리뷰에 도움이 필요한 개발자
• 코드 리뷰 피드백 작성에 어려움을 겪는 개발자
• 혼자 대부분의 리뷰를 담당하는 것이 힘든 시니어나 리드 개발자
• 팀의 코드 리뷰 태도를 개선하고자 하는 기술 리드 또는 리드 개발자
• 긴 코드 리뷰 주기에 지친 기술 리드 또는 엔지니어링 매니저
• 코드 리뷰 중시 문화를 만들고자 하는 테크 리드 또는 엔지니어링 매니저

1.2. 책의 구조

1.3. 코드 리뷰가 필요하다

1.3.1. 더 나은 어플리케이션

1.3.2. 팀의 이해 수준 향상

1.4. 팀 설득하기

• 코드 리뷰의 목표는 무엇인가?
• 변경사항에 대해 누가 알아야 하는가?
• PR을 리뷰할 사람은 어떻게 결정하는가?
• 리뷰어에게 얼마나 시간을 주어야 하는가?
• 최소 몇 명의 리뷰어가 필요한가?
• 핫픽스를 배포할 때는 어떻게 해야하는가?

1.5. 코드 리뷰 개선하기

• 고려사항
  • 내구성과 가치를 높이는 코드 작성은 팀의 핵심 목표여야한다.
  • 코드는 사람이 작성한다는 것을 기억해야 한다.

요약

• 코드 리뷰는 개발자가 서로의 코드가 합의된 표준을 통과하는지 검토하는 프로세스다. 검토는 간단하게 이루어질 수도 있고, 공식 회의나 PR을 통해서 이루어질 수도 있다.
• 코드 리뷴는 소프트웨어 개발에서 예외사항이 아닌 표준이 되어야 한다. 코드 리뷰는 명확하고, 읽기 쉬우며, 유지 관리가 쉬운 코드를 통해 더 나은 어플리케이션을 만들고, 지식 전달, 정보 공유, 기록 저장 메커니즘을 통해 팀의 코드베이스와 서로에 대한 이해를 높이기 때문이다.
• 훌륭한 코드 리뷰는 응집력 있는 팀을 기반으로 구축된다. 응집력 있는 팀이란 모든 구성원이 존중받고, 가치를 인정받으며, 동등한 일원으로 대우받는 팀이다.

Chapter 2. 코드 리뷰 분석하기

2.1. 코드 리뷰 시스템

• 사람 주도 시스템
• 도구 기반 시스템

2.3.1. 사람 주도

• 동기식 회의, 토론, 대면 리뷰 프로세스 등
• 지식 전달과 공유 및 멘토링 목표를 이루는데 큰 도움이 될수 있다.
• 팀을 구축하는 시스템에 대한 인식과 친밀도를 높일수 있다.
• 동기적 특성으로 인해 공식 문서화 및 기록은 팀의 노력이 매우 중요해진다.

2.1.2. 도구 기반

• 완전 도구 중심의 코드 리뷰 시스템은 대규모 또는 분산된 팀에 특히 효과적이다.
• 단점
  • 검토 시간이 지연되거나 길어진다.
  • 잘못된 도구를 선택하여서 도구의 특이점에 적응하느라 불필요한 마찰을 일으킬수 있다.

2.1.3. 혼합형

2.2. 코드 리뷰는 어떻게 작동할까?

2.2.1. 현재의 코드 리뷰 워크플로

• 코드 리뷰의 네가지 요소
  • 새로운 코드나 변경된 코드
  • 한명 이상의 리뷰어
  • 리뷰 메커니즘
  • 승인 조건

2.2.2. 우리의 코드 리뷰 (PR 워크플로)

2.3. 훌륭한 PR의 요소

2.3.1. 제목: ‘what’

• feat, fix, docs, chore, breaking
• PR의 ‘무엇’을 최대한 명확하고, 간결하게 설명한다.
• 제목이 의도치 않게 잘리는 것을 방지하기 위해 적절한 길이로 유지한다.
• 카테고리 접두어를 사용하면 몇 글자만으로도 많은 세부 정보와 맥락을 나타낼 수 있다.
• 제목은 리뷰어가 PR의 맥락을 이해하고 제대로 준비할 수 있도록 도와준다. 리뷰어는 작성자를 도울 수 있도록 명확하고 명료한 제목을 작성하도록 노력해야 한다.

2.3.2. 디스크립션: ‘why’

• feat

  • 맥락/타당성
  • 사용 사례
  • 정상 동작 확인 결과
  • 미리 보기(가능한 경우)
  • 문서화
  • 테스트 여부/범위

• fix:

  • 맥락/타당성
  • 관련 티켓/이슈 번호
  • 수정 전후 비교
  • 테스트방법
  • 문서화
  • 테스트 여부/범위

• docs:

  • 맥락/타당성
  • 관련 티켓/이슈 번호
  • 사용 사례
  • 미리 보기(가능한 경우)

• chore:

  • 맥락/타당성

• breaking:

  • 문맥/타당성
  • 정상 동작 확인 결과
  • 영향이 미치는 프로젝트
  • 주요 일정(기한 등)
  • 배포 후 문제 발생 시 대처 방안/향후 작업
  • 문서화
  • 테스트 여부/범위

• 맥락/타당성

  • 왜 해당 방식으로 구현했는가?
  • 왜 더 쉬운 방법이 아니라 해당 접근법을 사용했는가?
  • 작업 과정에서 공개/비공개로 이루어진 논의는 무엇인가?
  • 어떤 결정사항(본인 또는 다른 사람)이 개발에 영향을 미쳤는가?
  • 현재 단계에 도달하기 위해 어떤 과정을 거쳤는가?

• 사용 사례

  • 때로는 맥락/타당성 부분과 내용이 중복될수도 있지만 이는 전혀 문제가 되지 않는다. 반대로 맥락에 대한 설명이 충분히 명확하고 간결하다면 사용 사례가 불필요할 수도 있다. 따라서 상황에 따라 결정하면 된다.

• 테스트 방법

• 관련 티켓/이슈 번호

• 문서화

• 수정 전후 비교

• 영향받는 프로젝트(중요한 변경)

• 배포 후 문제 발생 시 대처 방안/향후 작업(중요한 변경):

  • 마이그레이션 방법(migration step)
  • 사용 중단 방법(deprecation step)

• 레이블

  • 너무 많으면 장점이 줄어든다.
  • 팀에서 처음으로 레이블을 사용하기 시작한다면 feature와 bug 두가지 먼저 하는 걸 추천한다.

• 리뷰 상태

  • draft
  • ready for review
  • in review
  • needs fixes
  • approved

2.4. 코드 리뷰 참여자와 기대사항

2.4.1. 리뷰어

• 주어지는 영향력:
  • PR이 하나의 논리적인 동작에 초점을 맞추고 있는가?
  • PR이 변경사항(또는 관련 정보 링크)에 대한 맥락을 제공하는가?
  • 코드가 PR의 맥락과 일치하는가?
  • 코드가 존재하는 승인 기준을 만족하는가?
  • 리뷰 중인 코드를 이해할 수 있는가?
  • 흐름이 논리적인가?
  • 다시 읽어야 할 정도로 명확하지 않은 부분이 존재하는가?
  • 작성자가 놓친 시나리오나 에지 케이스가 있는가?
  • 히스토리나 코드에 영향을 미칠만한 부분들이 제대로 고려되었는가?
  • 변경사항이 전체 시스템과 잘 맞는가?
• 리뷰어는 리뷰가 끝난 코드에 대해 책임이 있다.
  • 간략하게 흝어보기만 하는 리뷰는 하지 말아야한다. 상황에 상관없이 리뷰어는 적절하게 리뷰를 진행해야할 의무가 있다.
  • PR에서 대부분의 작업은 자동화되어야 한다
• 리뷰어의 역할과 책임
  • 자존심을 내려놓자
  • 개발자가 아닌 코드에 집중한다
  • 간단한 피드백은 코멘트를 사용한다
  • 복잡한 피드백은 직접 커뮤니케이션 한다.
  • 리뷰어로서의 영향력을 남용하지 않는다.
  • 리뷰를 대충 흝어보지 않는다.
  • 승인한 코드에 대한 책임을 진다.

2.4.2. 작성자

• 스스로 첫 번째 리뷰어가 된다.
  • 자동화 도구를 실행하고 검사에서 발견된 문제를 수정했는가?
  • 승인 기준을 충족했는가?
  • PR과 관련된 파일만 포함되었는가?
  • 코드와 PR에 제공된 정보만으로 코드의 변경사항을 논리적으로 설명할 수 있는가?
  • 리뷰 중 예상되는 질문이 고려되었는가?
  • 내부 지식이나 기존 경험 없이도 PR에 제공된 정보만으로 모든 질문에 답할 수 있는가?
  • 에지 케이스가 고려되었는가?
  • 코드가 시스템 전체의 아키텍처와 잘 맞는가?
• PR을 리뷰하기 쉽게 관리하자
  • 개별 변경사항 또는 기능에 집중한다.
  • 관련된 파일만 포함한다.
  • 여러 부분의 변경은 각각 별도의 리뷰로 나눈다.
  • 10~20분 내로 리뷰할 수 있는 크기로 만든다.
  • 기본적으로 500줄 이하로 만든다.
  • 기본적으로 20개 미만의 파일로 만든다.
• PR을 이해하기 쉽게 만들자
  • 제목이 간결한가?
  • 변경사항에 대한 설명이 명확한가?
  • 변경사항과 관련된 모든 정보와 맥락이 포함되어 있는가?
  • 완성된 관련 문서가 PR에 포함되어 있는가?
  • 커밋 메시지가 충분한 의미를 담고 있으며, 명확하고 개별적인가?
  • 관련 테스트가 생성 또는 업데이트되고 PR에 포함되어 있는가?
  • 티켓 번호나 스프린트 항목이 연결되어 있는가?
  • 적절한 레이블이 할당되어 있는가?
  • 사전 검사, 테스트 실행, 기타 자동화된 요구사항이 실행 완료되고 통과했는가?
• 코드와 자신을 동일하게 여기지 말자
• 작성자의 역할과 책임
  • 자신이 첫번째 리뷰어가 되자. 리뷰어의 질문을 예상하여 미리 답을 제공한다.
  • PR을 관리하기 쉽게 만들자. 작고 개별적이며 충분한 맥락을 포함한다.
  • PR을 이해하기 쉽게 만들자. 리뷰 준비 완료를 위해 호가인할 모든 사항을 체크한다.
  • 개발자는 코드가 아니다. 건설적인 피드백은 작성자에 대한 공격이 아니라 코드베이스를 개선할 수 있는 기회다.
  • 리뷰어나 작섲아 자신이 아닌 피드백에 집중한다.

2.4.3. 팀

• 팀이 프로세스의 속도를 결정한다.
• 코드 리뷰 프로세스의 품질은 팀 전체의 운영방식에 달려 있다.
• 팀의 역할과 책임
  • 모두가 프로세스를 준수하도록 한다.
  • 가능하다면 도구를 사용해 자동으로 갖에하도록 한다.
  • 비상 절차는 함께 개발하고 최소한으로 사용한다.
  • 모든 프로세스를 자주 점검한다. 예감이 안 좋으면 실제로 문제가 있을 가능성이 크다.
  • 프로세스를 우회할 때는 모두에게 공유한다.
  • 서로 책임감을 갖는다.
  • 모두가 코드베이스에 대해 공동 책임을 진다.

2.4.4. 관리자

• 지원은 여러 가지 형태로 가능하다.
• 격려란 코드 리뷰 문화를 조성하는 것이다
• 관리자의 역할과 책임
  • 코드 리뷰가 원할하게 진행되도록 지원한다.
  • 코드 리뷰를 장려하는 문화를 조성한다.
  • 코드 리뷰 프로게스와 팀에 영향을 미칠 수 있는 문제를 감시하고 해결하거나 제거한다.
  • 코드 리뷰를 부가적인 업무나 선택사항이 아니라 개발 프로세스의 필수 과정으로 만든다.
  • 모든 팀원이 리뷰 프로세스를 따르도록 한다.

2.4.5. 조직

• 조직이 코드 리뷰를 대하는 방식
• 코드 리뷰에 저항을 갖는 조직 설득하기
  • 자신의 팀부터 시작
    • 개발 워크숍, 스프린트 회고, 모두가 참여하는 팀 회의에서 코드 리뷰의 개념을 소개한다.
    • 코드 리뷰 프로세스를 문서화한다. 어떤 도구를 선택하고 설정을 구성했는지 기록하고, 효과적이거나 효과적이지 않았던 정책들을 정리한다.
    • 팀에서 코드 리뷰 관련 사항이 자리를 잡고 워크플로가 자연스럽게 정착되면 이를 공식화 한다.
  • 개발한 가이드라인을 다른 개발팀과 공유
  • 기술 리드, 매너지와 대화
  • 기술 리드, 매니저라면 리뷰를 적극 옹호
• 소프트웨어 개발팀 성과 측정을 위한 엔지니어링 지표
  • DORA 지표
  • 배포빈도
    • 개발팀이 운영환경에 코드를 배포하는 빈도
    • 하루 평균 배포 횟수
    • 팀의 작업과 배포 프로세스의 효율성을 나타냄
    • 팀이 고객에게 가치를 제공하는 빈도를 나타냄
  • 평균 변경 리드 타임
    • 코드 커밋 후 성공적인 실행까지 소요 시간. 사이클 타임이라고도 함
    • 커밋 후 운영환경에서 실행까지 걸리는 평균 시간
    • 팀의 속도를 추적하는 지표. 빠른 팀은 최적화된 프로세스, 트린팀은 프로세스의 비효율성을 의미할 수 있음
    • 더 빠른 제공 속도는 매출의 증가와 고객 갱신을 향상에 기여
  • 평균 복구 시간
    • 배포 실패 시 복구 시간
    • 운영 환경에서 버그나 장애가 보고되고 문제 해결까지 평균 시간
    • 프로덕션에서 발생한 문제를 팀이 얼마나 빠르게 이해하고 해결할 수 있는지를 타나 냄. 시간일 짧을수록 장애발생시 빠르게 정상 상태로 복구할 수 있다는 자신감을 가질 수 있음
    • 어떤 형태라도 다운 타임은 조직에 부정적인 영향. 복구 시간이 빠를수록 조직에 미치는 영향도 줄어듦
  • 변경 실패율
    • 운영 환경 배포 실패 빈도
    • 비율은 실패 횟수를 배포 횟수로 나눈값(백분율)
    • 개발팀이 구축하는 품질을 나타냄. 실패율이 높으면 낮은 품질의 소프트웨어와 고객의 불만을 초래할 수 있음
    • 버그 수정과 코드 롤백은 비용이 듦. 이러한 작업은 새로운 기능 개발과 고객에게 가치를 제공할 시간을 줄어들게 함

Chpater 3. 팀의 첫 코드 리뷰 프로세스 구축하기

3.1. 목표 설정하기

• 코드 리뷰 프로세스를 통해 어떤 기능을 수행하려고 하는가?
• 코드 리뷰 프로세스를 통해 어떤 목표를 달성하고 싶은가?

3.1.1. 버그 발견

• 논의포인트
  • 코드리뷰 단계에서 명백한 버그는 없어야한다.
  • 코르 리뷰 프로세스에서 버그를 찾는 것이 가능하며 이를 목표로 잡아야한다.
  • 코드 리뷰는 단위 테스트로 잡을 수 없는 버그를 찾는 것이 목적이다.
• 스스로 질문
  • 팀과 자연스럽게 협력하여 문제를 찾아내는가?
  • 동료가 코드를 병합하기 전에 검토를 한번 더 요청하는가?
  • 어떤 형태로든 테스트를 진행하고 있음에도 운영 환경에서 문제가 발생하는가?

3.1.2. 코드베이스의 안정성과 유지 보수성

• 복잡성 관리, 일관성 유지, 확장성 고려, 테스트 수행, 코딩 컨벤션과 팀 표준 준수, 단위테이스 에지케이스
• 스스로 질문
  • DORA 지표를 기준으로 팀이 하위-중간의 수준에 위치한다면 코드베이스의 안정성과 유지 보수성은 코드 리뷰에서 가장 먼저 고려해야 할 목표가 된다.
  • DORA 지표가 상위-엘리트 수준이라면 이미 코드가 상당히 안정적이고 유지 보수성도 좋을 가능성이 크다. 이때는 코드의 안정성과 유지 보수성을 명시적인 목표로 설정할 필요가 없을 수도 있지만, 지속적으로 유지하는 방향으로 코드 리뷰를 활용할 수도 있다.

3.1.3. 지식 전달과 정보 공유

• 지식 전달: 개인 또는 그룹이 가진 지식을 다른 사람이나 팀에게 전달하는 과정
• 정보 공유: 팀원 간에 쉽게 접근할 수 있는 환경에서 정보를 자유롭게 교환하는 과정
• 휴가지수:
  • 버스 지수
• 코드리뷰 프로세스를 지식 전달과 정보 공유의 수단으로 활용하려면:
  • how보다는 why를 문서화한다
  • 적절한 리뷰어를 선택한다
  • 새로운 팀원이나 경험이 적은 팀원을 정보 제공을 위한 리뷰어로 추가한다

3.1.4. 멘토링

3.1.5. 기록 보관/변경 이력 관리

3.1.6. 자신의 코드리뷰 목표 선택하기

3.2. 도구 선택하기

3.3. 가이드라인 설정하기

3.3.1. 팀의 워크플로

• 새로운 팀원들이 코드 리뷰 프로세스를 이해하는 데 도움을 준다.
• 모든 팀원이 워크플로를 명확하게 참고할 수 있도록 돕는ㅏ.
• 워크플로를 따르는 사람이 각 단계의 기대사항과 단계 전후에 어떤 일이 발생하는지에 따라 이해를 돕는다.
• 팀 전체가 동일한 워크플로를 공유하고 일관된 방식으로 코드 리뷰를 진행하도록 돕는다.
• 결정 사항
  • 시작 지점
  • 리뷰 요청 액션
  • 리뷰 매커니즘
  • 피드백 사이클 매커니즘
  • 승인 조건
  • 종료 지점

3.3.2. 리뷰의 중점

• 복잡성: 코를 이해할 수 있고 흐름을 쉽게 따라갈 수 있는가? 나중에 다른 개발자가 다시 봤을 때도 명확한 내용인가? 코드를 사람 친화적이고 직관적으로 만들 수 있는가? 미래에 이 코드를 수정하는 것이 용이한가? 일시로 짠 코드가 포함되어 있어 영구적인 방식으 개선할 필요가 있는가?
• 일관성: 제안된 변경사항이 프로젝트에서 이미 사용하고 있으며 신뢰할 수 있는 디자인 패턴과 관행을 따르고 있는가? 기존의 코드 또는 라이브러리를 재사용할 수 있는가?
• 컨벤션: 업계 표준이 준수되고 있는가? 라이브러리, 프레임워크, 언어, 기타 확림된 컨벤션을 따르고 있는가?
• 크로스 플랫폼 호환성: 코드베이스가 다양한 플랫폼을 고려해야하는가? 의존성이 특정 플랫폼에 종속되는가? 다른 개발자도 쉽게 코드를 실행할 수 있는가?
• 문서화: 문서가 없을

3.3.3. PR 승인을 막는 요인

• 허용 요인 이슈: 별도의 PR이나 건설적인 피드백으로 해결이 가능하여 PR승인을 차단해서는 안 되는 이슈
  • 스타일 선호
  • 사소한 서식의 불일치
  • 문서의 사소한 문제
  • 누락된 선택적 기능
  • 경미한 리팩터링 기회
  • 관련 없는 개선사항
• 차단 요인 이슈: 해결이 필요하여 PR 승인을 차단해야 하는 이슈
  • 핵심 기능
  • 보안 문제
  • 코드 표준 위반
  • 깔끔하지 않은 코드
  • 회귀 발생
  • 성능 문제
  • 테스트 실패

3.3.4. 승인 정책

• 누가 PR을 승인할 수 있는가?
  • 이성적으로는 개발팀의 모든 구성원이 PR을 승인할수 있어야한다.
  • 매니저, 기술 리드, 프로그램 매니저, QA 엔지니어 등?
  • 정보 제공 목적인 리뷰어에게도 완전한 승인 권한을 부여할까?
  • 외부팀도 PR을 승인할 수 있을까?
  • 리뷰어 수를 인위적으로 늘려 너무 많은 사람이 리뷰를 하게 되면 다른 사람에게 떠넘길 가능성이 커질수 있다.
  • 비상 상황에서 승인 권한을 가진 인원을 제한할까?
• 얼마나 많은 승인이 필요할까?
  • 최소 2명의 리뷰어 승인을 강력히 권장한다.

3단계 결과물

• 네 가지 필수 가이드라인 설정
  • 워크플로: 코드 리뷰 세부 단계를 계획하고 개요를 작성한다.
  • 리뷰의 중점: 코드 리뷰 중 집중할 사항을 정의한다.
  • 허용 vs. 차단 이슈: PR 승인을 허용할 수 있는 문제와 차단할 수 있는 문제를 명확히 구분한다.
  • 승인 정책: 누가 PR을 승인할 수 있는지와 필요한 승인자의 수를 결정한다.

3.4. 프로세스 개선하기

• 논의
• 결정
• 공유

Part 2. 고급 코드 리뷰를 위한 필수 요소

Chapter 2. 팀 워킹 어그리먼트

4.1. 팀 워킹 어그리먼트란?

• TWA: Team Working Agreement
• 암묵적인 사회적 기대를 명확하고 강제하는 규칙으로 전환한다.
• 자동화를 할 수 있는 부분은 반드시 자동화를 해야 한다

4.2. 팀 워킹 어그리먼트로 팀 기대치 설정하기

• 합리적인 PR 응답 시간
• 명명 규칙과 표준
• 차단 이슈와 허용 이슈
• 팀 스타일 가이드

4.3. 팀 워킹 어그리먼트 수립하기

• 처음에는 역할의 행동 기대치에 대한 의견을 요청하는 것이 어색하게 느껴질 수도 있다.
• 공감하는 태도와 체계적인 방식으로 논의한다면 팀의 가장 가치 있는 인사이트를 얻을 수 있는 기회가 될 수 있다.

4.3.1. 팀에 팀 워킹 어그리먼트가 꼭 필요할까?

• 구글의 엔지니어링 방법론:
  • https://soojin.ro/blog/google-code-review-guide
• gitlab 코드리뷰 가이드라인: https://docs.gitlab.com/development/code_review/
• 미국 GSA(연방총무청) 기술 혁신 서비스 가이드: https://handbook.18f.org/18f/chapters/engineering/
• Yelp Engineering 코드 리뷰 가이드라인: https://engineeringblog.yelp.com/2017/11/code-review-guidelines.html