효과적인 코드 리뷰 문화: 비난이 아닌 배움의 장

들어가며

코드 리뷰는 비난이 아닌 배움이며, 팀의 생산성과 지속가능성을 높이는 가장 현실적인 방법이다.

2021년 7월 입사 후 약 9개월간 10명 이상의 개발자들과 지속적으로 코드 리뷰를 진행해왔다.

현재도 코드 리뷰는 잘 진행되고 있지만, 더 나은 방법이 분명 존재한다는 생각이 들었다.

OKKY 세미나와 우아한테크세미나에서 백명석님의 발표를 듣고, 코드 리뷰에 대한 관점을 정리할 수 있었다. 이 글에서는 그동안의 경험과 배운 내용을 바탕으로 효과적인 코드 리뷰 문화를 구축하는 방법을 공유한다.

왜 코드 리뷰를 해야 하는가?

우리가 살고 있는 시대

“Software is eating the world” - Marc Andreessen

이제 소프트웨어는 모든 산업의 핵심이 되었다. Non-Tech 산업에서조차 개발자 수가 급증하고 있다:

농업: 스마트팜, IoT 센서 데이터 분석
금융: 핀테크, 디지털 뱅킹
헬스케어: 원격 진료, AI 진단
제조: 스마트 팩토리, 자동화

이러한 변화 속에서 개발 조직의 성능(생산성)이 기업의 경쟁력을 직접적으로 좌우한다.

개발 조직의 생산성이란?

많은 조직이 겪는 전형적인 문제:

출시 회차 증가
    ↓
개발자 수 증가
    ↓
코드베이스 복잡도 증가
    ↓
생산성 저하

잘못된 접근: 설계 품질을 희생하면 단기적으로는 속도가 빨라 보이지만, 장기적으로는 생산성이 급격히 하락한다.

기술 부채의 대가:

버그 수정 시간 증가
새 기능 개발 속도 저하
코드 이해에 소요되는 시간 증가
팀원 간 커뮤니케이션 비용 증가

The only way to go fast, is to go well. – Robert C. Martin

올바른 접근: 처음부터 설계 품질을 유지하면서 개발하는 것이 결국 가장 빠른 길이다.

소프트웨어 공학의 본질

건축 공학 vs 소프트웨어 공학

소프트웨어 공학을 이해하기 위해 건축 공학과 비교해보자.

구분	건축 공학	소프트웨어 공학
설계	UML, CAD 도면	소스 코드 자체
빌드 비용	매우 높음 (수억~수조)	거의 없음 (컴파일/배포)
변경 비용	매우 높음	상대적으로 낮음
유지보수	상대적으로 낮음	매우 높음 (전체 비용의 60-80%)

핵심 차이점:

1. 소프트웨어에서 설계 = 코드

건축에서는 도면이 설계, 건물이 결과물
소프트웨어에서는 코드가 설계이자 결과물
컴파일/배포는 자동화되어 비용이 거의 없음

2. 유지보수 비용의 차이

건축: 설계 → 시공 → 유지보수 (소규모)
소프트웨어: 설계(코드) → 빌드(자동) → 유지보수(대규모)

결론:

좋은 설계 = 클린 코드
좋은 개발자 = 설계를 잘하는 사람 = 클린 코드를 작성하는 사람

소프트웨어 개발에서 코드의 품질이 곧 설계의 품질이며, 이것이 장기적인 생산성을 결정한다.

코드 리뷰의 목적

주요 목적

1. 결함 사전 검출

버그 발견
잠재적 장애 요인 제거
성능 문제 식별
보안 취약점 발견

2. 변경 비용 감소

결함 발견 시점에 따른 비용:

코드 리뷰 단계: 1x
테스트 단계: 10x
운영 배포 후: 100x

코드 리뷰에서 발견하면 수정 비용이 가장 낮다.

3. 학습과 지식 공유

팀원 간 코드 스타일 통일
새로운 기술, 패턴 학습
도메인 지식 공유
베스트 프랙티스 전파

4. 집단 코드 오너십

특정 개발자만 아는 코드 제거
팀 전체가 코드베이스를 이해
버스 팩터(Bus Factor) 개선
인수인계 부담 감소

5. 팀 문화 개선

팀 결속력 강화
협업 능력 향상
긍정적인 개발 문화 형성

코드 리뷰의 절차와 역할

역할 정의

저자(Author):

코드 작성
Pull Request(Merge Request) 생성
리뷰 요청
피드백 반영

리뷰어(Reviewer):

코드 이해 및 분석
피드백 제공
Merge 여부 판단

좋은 Pull Request란?

리뷰어의 시간을 존중하는 PR:

1. 명확한 제목과 설명

Bad:
제목: 수정

Good:
제목: [USER-123] 사용자 비밀번호 암호화 알고리즘 변경

설명:
## 변경 이유
- 기존 MD5 알고리즘의 보안 취약점
- OWASP 권장 사항 준수 필요

## 주요 변경 사항
- BCrypt 알고리즘으로 변경
- 비밀번호 해시 로직 리팩토링
- 마이그레이션 스크립트 추가

## 테스트
- 단위 테스트 추가
- 기존 사용자 로그인 검증 완료

2. 작은 PR 크기

이상적인 PR 크기: 200-400 라인 이하
최대 크기: 500 라인

큰 PR의 문제점:

리뷰 시간 과다 소요
피로도 증가로 인한 집중력 저하
버그 발견 확률 감소
피드백 반영 어려움

3. 짧은 리뷰 주기

작은 PR + 자주 리뷰 > 큰 PR + 드문 리뷰

4. 컨텍스트 제공

// AS-IS
public void process(String data) {
    // 복잡한 로직...
}

// TO-BE
public void process(String data) {
    validateData(data);
    parseData(data);
    saveData(data);
}

PR 설명에 변경 이유와 주요 포인트를 명시하면 리뷰어가 빠르게 이해할 수 있다.

왜 코드 리뷰는 어려운가?

심리적 장벽

1. 코드 비판을 개인 비판으로 받아들임

리뷰어: "이 메서드는 너무 길어서 분리하는 게 좋겠습니다."

저자의 잘못된 해석:
"내 코드가 나쁘다는 거야? 내가 못한다는 건가?"

올바른 해석:
"코드를 더 좋게 만들 수 있는 제안이구나."

2. 텍스트 기반 소통의 한계

텍스트에는 톤, 표정, 맥락이 없어 오해가 발생하기 쉽다.

Bad (명령조):
"이렇게 하세요."

Good (제안):
"이렇게 하면 가독성이 더 좋아질 것 같습니다."

3. 권위 차이

선임이 리뷰하면 후임은 의견을 내기 어려워진다.

해결 방법:

리뷰는 직급이 아닌 코드에 집중
후임도 선임 코드를 리뷰하는 문화
모든 리뷰 코멘트는 동등하게 취급

핵심 원칙

코드 리뷰는 공격이 아니라 토론과 공유의 장이다.

코드 리뷰를 잘하는 실전 기법

1. 컴퓨터가 잘하는 일은 컴퓨터에게

자동화해야 할 항목:

코드 포맷팅 (Prettier, Black, Google Java Format)
코딩 스타일 검사 (ESLint, Checkstyle, SonarLint)
정적 분석 (SonarQube)
단위 테스트 실행

설정 예시:

# .github/workflows/pr-check.yml
name: PR Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Code Format Check
        run: npm run format:check
      
      - name: Lint
        run: npm run lint
      
      - name: Test
        run: npm test
      
      - name: SonarQube Scan
        run: sonar-scanner

효과:

스타일 논쟁 제거
리뷰 시간 단축
본질적인 문제에 집중

2. 리뷰 전략

즉시 시작

PR 생성 → 즉시 리뷰 시작 (1시간 이내)

지연될수록:

저자는 다른 작업으로 컨텍스트 전환
피드백 반영 비용 증가
배포 지연

한 라운드는 하루 이내

리뷰어 피드백 → 저자 수정 → 재검토 (24시간 이내)

고수준 → 저수준 순서

1차 리뷰 (High Level):
- 아키텍처, 설계
- 버그, 보안
- 성능 문제

2차 리뷰 (Low Level):
- 네이밍
- 주석
- 가독성
- 코드 스타일

이유: 설계가 변경되면 저수준 피드백이 무의미해질 수 있음

3. 리뷰 코멘트 원칙

PR 범위 존중

Bad:
"이 파일 말고 다른 파일에 있는 이 함수도 고치세요."

Good:
"[Nit] 나중에 시간 될 때 관련 함수도 같이 리팩토링하면 좋을 것 같습니다."

Nit 태그 활용

[Nit] 변수명을 더 명확하게 하면 어떨까요?

Nit (Nitpick): 꼭 반영하지 않아도 되는 선택적 개선 사항

점진적 개선

목표: 코드 레벨을 한두 단계 끌어올리기

현재 레벨: 3
목표 레벨: 4-5 (X: 10)

완벽을 요구하지 말고, 이전보다 나아지는 것을 목표로 한다.

4. 구체적인 리뷰 체크리스트

설계 관점:

단일 책임 원칙(SRP) 준수
의존성 방향이 올바른가
확장 가능한 구조인가
중복 코드는 없는가

기능 관점:

요구사항을 충족하는가
엣지 케이스 처리
에러 핸들링
성능 문제는 없는가

가독성 관점:

의도가 명확한가
네이밍이 적절한가
복잡도가 높지 않은가
주석이 필요한가

테스트 관점:

테스트가 충분한가
테스트가 의미 있는가
테스트가 명확한가

피드백 커뮤니케이션 원칙

절대 하지 말아야 할 것

1. 인신공격

Bad:
"너는 왜 이렇게 짰어?"
"이것도 모르고 개발해?"
"항상 이런 실수를 하네요."

2. 모호한 비판

Bad:
"이 코드는 별로네요."
"좀 이상한데요?"

권장하는 방식

1. I-Message 사용

You-Message (공격적):
"당신의 코드는 이해하기 어렵습니다."

I-Message (객관적):
"이 부분을 이해하는 데 시간이 걸렸습니다."

2. 명령이 아닌 제안

Bad (명령):
"이 클래스를 분리하세요."

Good (제안):
"이 클래스를 분리하면 어떨까요?"
"이렇게 하면 더 좋을 것 같습니다."

3. 원칙 기반 설명

Bad:
"이 클래스를 분리하는 게 좋겠습니다."

Good:
"이 클래스가 사용자 검증과 데이터 저장이라는 
두 가지 책임을 가지고 있어 이해하기 어려웠습니다. 
단일 책임 원칙(SRP) 관점에서 분리하면 
각 클래스의 목적이 더 명확해질 것 같습니다."

원칙 예시:

SOLID 원칙
DRY (Don’t Repeat Yourself)
KISS (Keep It Simple, Stupid)
YAGNI (You Aren’t Gonna Need It)

4. 구체적인 예시 제공

Bad:
"이 부분을 개선해주세요."

Good:
"이 부분을 다음과 같이 개선하면 어떨까요?

[Before]
if (user != null && user.isActive() && user.getRole() == ADMIN) {
    // ...
}

[After]
if (isAdminUser(user)) {
    // ...
}

private boolean isAdminUser(User user) {
    return user != null 
        && user.isActive() 
        && user.getRole() == ADMIN;
}
"

칭찬에 인색하지 말 것

좋은 코드를 발견하면 반드시 언급:

"이 부분 정말 잘 짰네요!"
"이 패턴 사용한 거 좋습니다."
"테스트 케이스가 매우 명확하네요."
"이전보다 많이 개선되었습니다."

효과:

긍정적인 분위기 형성
학습 효과 증대
리뷰에 대한 거부감 감소
팀 결속력 강화

원칙: 리뷰어는 감시자가 아니라 팀 동료다.

교착 상태 대처 방법

교착 상태 신호

1. 감정적인 대응

"그렇게 하면 안 됩니다."
"제 방식이 더 낫습니다."
"왜 자꾸 이렇게 하라고 하세요?"

톤이 점점 공격적으로 변한다.

2. 반복되는 논쟁

리뷰 라운드 1: "A 방식이 좋겠습니다."
리뷰 라운드 2: "여전히 A 방식이 좋겠습니다."
리뷰 라운드 3: "계속 B 방식을 고집하시네요."

몇 차례 반복되어도 합의점을 찾지 못한다.

3. 침묵

코멘트에 대한 응답이 없거나, 형식적인 답변만 한다.

해결 방법

1. 직접 만나서 대화

"커피 한잔하면서 이야기할까요?"
"잠시 시간 내서 같이 화면 보면서 얘기해요."

대면 또는 화상 회의로 전환하면:

톤과 표정으로 의도 전달
즉각적인 질의응답
오해 신속 해소

2. 제3자 의견 요청

"@팀리더님, 이 부분에 대해 의견 주실 수 있을까요?"
"다른 팀원분들도 의견 부탁드립니다."

3. 짝 프로그래밍

"같이 코드 보면서 페어 프로그래밍 할까요?"

실시간으로 같이 코드를 작성하면서 해결.

4. 결정 기준 합의

"우리 팀의 코딩 컨벤션 문서를 만들어서 
다음부터는 기준에 따라 판단하는 게 어떨까요?"

5. 타임박스 설정

"이 부분은 일단 현재 방식으로 진행하고, 
다음 스프린트에서 개선하는 걸로 하면 어떨까요?"

완벽을 추구하다 배포가 지연되는 것보다, 점진적 개선이 나을 때가 있다.

코드 리뷰 문화 정착을 위한 가이드

개인 차원

1. 스스로 모범이 되자

남을 바꾸려 하지 말고, 자신이 먼저 좋은 리뷰어/저자가 되자.

좋은 저자:

작은 PR 작성
명확한 설명 제공
피드백 긍정적으로 수용
빠른 응답

좋은 리뷰어:

신속한 리뷰
건설적인 피드백
칭찬 아끼지 않기
배움의 자세

2. 작은 PR, 자주 리뷰

하루 1-2개의 작은 PR > 주말에 1개의 큰 PR

3. 배우는 자세 유지

"이 방식은 처음 보는데, 왜 이렇게 하셨나요?"
(비판이 아닌 진짜 궁금증)

후임의 코드에서도 배울 점이 있다.

팀 차원

1. 리더의 관심과 의지

리더가 코드 리뷰를 중요하게 생각해야 팀 문화로 정착된다.

리더가 할 일:

코드 리뷰 시간 확보
리뷰 참여 독려
좋은 리뷰 사례 공유
리뷰 문화 개선 논의

2. 코드 리뷰 가이드 문서 작성

# 우리 팀의 코드 리뷰 가이드

## 기본 원칙
- 존중과 배려
- 건설적인 피드백
- 빠른 응답

## PR 작성 규칙
- 크기: 400 라인 이하
- 제목: [JIRA-123] 명확한 설명
- 설명: 변경 이유, 주요 변경사항, 테스트 방법

## 리뷰 우선순위
1. 버그, 보안
2. 설계, 성능
3. 네이밍, 가독성

## 코멘트 템플릿
- [Question] 질문
- [Suggestion] 제안
- [Nit] 선택적 개선
- [Blocker] 반드시 수정 필요

3. 정기적인 회고

스프린트 회고에서:
- 이번 주 리뷰는 어땠나요?
- 개선할 점은 무엇인가요?
- 좋았던 리뷰 사례 공유

4. 리뷰 메트릭 추적 (선택)

- 평균 리뷰 시간
- PR 크기 분포
- 리뷰 라운드 수
- 리뷰 참여율

과도한 메트릭 관리는 부작용이 있으니 주의.

조직 차원

1. 리뷰 시간을 공식 업무 시간으로 인정

리뷰는 “남는 시간에 하는 것”이 아니라 핵심 업무다.

2. 리뷰 문화 우수 사례 공유

사내 세미나, 테크 블로그 등으로 공유.

3. 도구 지원

GitHub, GitLab, Bitbucket
코드 리뷰 전용 도구 (Gerrit, Phabricator)
자동화 파이프라인

현실적인 기대치 설정

리뷰는 만능이 아니다:

코드 리뷰로 해결되는 것:
- 설계 개선
- 버그 일부 발견
- 지식 공유
- 팀 문화 개선

코드 리뷰로 해결되지 않는 것:
- 100% 버그 제거
- 완벽한 설계
- 모든 성능 문제

리뷰는 완벽이 아닌 개선을 위한 도구다.

실전 사례

사례 1: 설계 개선

상황: 하나의 메서드에 200줄의 로직이 들어있는 PR

Bad 리뷰:

"이 메서드 너무 길어요. 나눠주세요."

Good 리뷰:

"이 메서드가 여러 책임을 가지고 있어서 
이해하는 데 시간이 걸렸습니다.

다음과 같이 분리하면 각 부분의 의도가 
더 명확해질 것 같습니다:

1. validate() - 입력 검증
2. transform() - 데이터 변환
3. persist() - 저장
4. notify() - 알림

어떻게 생각하시나요?"

사례 2: 버그 발견

상황: Null 체크가 누락된 코드

Bad 리뷰:

"NPE 날 것 같은데요?"

Good 리뷰:

"user 객체가 null일 수 있을 것 같습니다.
다음과 같은 경우에 null이 될 수 있을 것 같아요:

1. 사용자가 로그아웃한 경우
2. 세션이 만료된 경우

Optional을 사용하거나 null 체크를 추가하면 
어떨까요?

Optional.ofNullable(user)
    .map(User::getName)
    .orElse("Guest")

사례 3: 성능 개선

상황: 반복문 안에서 DB 조회

Bad 리뷰:

"이거 느릴 것 같은데요."

Good 리뷰:

"반복문 안에서 DB를 조회하고 있어서
데이터가 많아지면 성능 이슈가 발생할 수 있을 것 같습니다.

현재: N+1 쿼리 발생 (N = 상품 개수)
개선: Batch fetch 또는 JOIN 사용

예상 성능 개선:
- 현재: 100개 상품 → 100번 쿼리
- 개선 후: 100개 상품 → 1번 쿼리

JPA의 @BatchSize 또는 fetch join을 
사용하면 어떨까요?"

마무리

핵심 원칙 요약

코드 리뷰는 비난이 아니라 배움의 장
작은 PR, 자주 리뷰, 빠른 피드백
고수준부터 저수준 순서로
I-Message, 제안형, 원칙 기반 설명
칭찬에 인색하지 말 것
교착 상태는 대화로 해결
완벽보다 점진적 개선
리더의 관심과 의지가 핵심

마지막 메시지

완벽한 설계는 존재하지 않는다. 하지만 지금 할 수 있는 최고의 설계는 존재한다.

불완전함을 받아들이되, 배우는 문화를 포기하지 말자.

코드 리뷰는 팀의 미래를 위한 투자다.

오늘 리뷰한 코드가 내일의 생산성을 만든다.

시작하기

코드 리뷰 문화는 하루아침에 만들어지지 않는다.

오늘부터 할 수 있는 작은 실천:

다음 PR을 200줄 이하로 작성하기
동료의 PR에 긍정적인 코멘트 하나 남기기
피드백을 방어적이 아닌 학습의 기회로 받아들이기
팀 회고에서 코드 리뷰 개선 방안 논의하기

작은 실천이 모여 위대한 팀 문화를 만든다.

Reference

Twitter Facebook LinkedIn

동구리

들어가며

왜 코드 리뷰를 해야 하는가?

우리가 살고 있는 시대

개발 조직의 생산성이란?

소프트웨어 공학의 본질

건축 공학 vs 소프트웨어 공학

코드 리뷰의 목적

주요 목적

코드 리뷰의 절차와 역할

역할 정의

좋은 Pull Request란?

왜 코드 리뷰는 어려운가?

심리적 장벽

핵심 원칙

코드 리뷰를 잘하는 실전 기법

1. 컴퓨터가 잘하는 일은 컴퓨터에게

2. 리뷰 전략

3. 리뷰 코멘트 원칙

4. 구체적인 리뷰 체크리스트

피드백 커뮤니케이션 원칙

절대 하지 말아야 할 것

권장하는 방식

칭찬에 인색하지 말 것

교착 상태 대처 방법

교착 상태 신호

해결 방법

코드 리뷰 문화 정착을 위한 가이드

개인 차원

팀 차원

조직 차원

현실적인 기대치 설정

실전 사례

사례 1: 설계 개선

사례 2: 버그 발견

사례 3: 성능 개선

마무리

핵심 원칙 요약

마지막 메시지

시작하기

Reference

공유하기

댓글남기기

참고

헥사고날 아키텍처, 책으로는 이해 안 돼서 직접 만들어봤다

TLS 1.2 vs 1.3 성능 비교: 실측으로 확인한 12% 핸드셰이크 개선

JVM 메모리 구조 분석: Heap, GC, 그리고 Java 25의 변화

Business Exception의 적절한 로그 레벨은 무엇인가?