[CodeReadability] 8장 Code Reivew

Objective

코드 리뷰(Code Review)를 통해 코드의 가독성, 품질, 생산성을 높인다.

코드 자체만이 아니라 “리뷰 과정” 또한 효율적이고 협력적으로 설계해야 한다.

---

Key Results

• [KR1] 리뷰 요청자는 리뷰하기 쉬운 Pull Request(PR)을 만든다.
• [KR2] 리뷰 수행자는 코드를 “비판”이 아닌 “협업”의 관점에서 검토한다.
• [KR3] 리뷰의 핵심은 “변경의 의도와 책임 범위”를 명확히 하는 것이다.
• [KR4] PR의 크기와 구조를 조절해 리뷰 생산성을 높인다.
• [KR5] 리뷰 코멘트의 목적은 코드 품질 향상이 아니라 지속 가능한 팀 협업이다.

---

Part 1. 리뷰의 필요성과 본질

개념

코드 리뷰는 단순히 오류를 찾는 과정이 아니라,

• 가독성(Readability)
• 논리적 정확성(Logic correctness)
• 지식 공유(Knowledge sharing)
• 코드 일관성(Maintainability)
• 을 확보하기 위한 협업 프로세스이다.

---

리뷰의 두 가지 목적

구분	목적	주체
가독성(Readability)	타인이 읽을 때 쉽게 이해되게 하는 것	Reviewer
정확성(Correctness)	논리·엣지 케이스·동시성 등 검증	Author(작성자)

즉, 버그의 책임은 작성자에게, 가독성 검증의 책임은 리뷰어에게 있다.

---

Part 2. 리뷰 효율성 (Review Efficiency)

개념

• 코드 리뷰는 “시간”과 “집중력”을 소비하는 행위다.
• 리뷰 자체가 비효율적이라면 팀의 생산성 전체를 떨어뜨린다.

---

핵심 원칙

“읽기 쉬운 코드” = “리뷰하기 쉬운 코드”

즉,

• Pull Request(PR)의 범위를 명확히 하고, 크기를 작게 유지해야 한다.

---

Part 3. 리뷰 요청자(Reviewee)의 역할

---

3-1. 리뷰하기 쉬운 PR 만들기

개념

PR의 책임 범위(Scope of Responsibility) 를 명확히 하고, 리뷰 가능한 크기(Small Size) 로 쪼개야 한다.

---

예제 — PR 설명 작성

# Summary
- Add UserProfilePresenter for showing user info
- Implement data binding between View and UseCase
- Future plan: handle user avatar (TODO #1234)

해설

• Main purpose (무엇을 달성하려는가)
• Out of scope (이번 PR에 포함하지 않는 것)
• Future plan (다음 단계 계획)
• 을 명시해 Reviewer가 “리뷰의 범위”를 즉시 파악할 수 있게 한다.

---

문제 예제

# No Description
(파일만 20개 변경, 내용 없음)

→ 리뷰어는 “이게 무슨 기능인지, 어디서 끝나는지” 파악 불가.

→ 리뷰어 피로도 급상승, 논의 방향도 산만해짐.

---

해결

• PR 설명에 “무엇을 위한 변경인지” 반드시 작성
• 필요하다면 “Design Doc” 링크를 추가해 배경까지 공유

---

3-2. 작은 PR 유지 (Small Pull Request)

---

개념

“작은 PR은 좋은 리뷰의 시작이다.”

너무 큰 PR은 이해, 리뷰, 수정 모두 어렵다.

---

안티 패턴

• “이번 주 작업 전체를 한 PR에 넣는 방식”
• Reviewer가 한번에 수백 라인을 봐야 하는 구조

---

해결 — 큰 기능 나누기

1️⃣ Top-down 방식

• 우선 클래스/모듈 뼈대를 작성하고
• TODO(#12345) 로 향후 구현 계획을 명시

class UserProfilePresenter(
    val userProfileUseCase: UseCase,
    val profileRootView: View
) {
    fun showProfileImage() = TODO("#12345: implement later")
}

2️⃣ Bottom-up 방식

• 내부 Utility / Data / ViewModel 등 작은 단위부터 구현

object UserNameStringUtils {
    fun normalizeEmoji(userName: String): String = ...
}

---

추가 작업 분리 예시

object DateTimeTextFormatter {
    fun toClockText(epoch: Long): String = ...
}

→ 기존 중복 코드를 추출해 Utility화할 때는

별도 PR로 분리하고 순서를 조정(rebase)한다.

---

해결 풀이

• PR의 단위를 기능 단위로 유지하면 리뷰 집중도가 높아진다.
• “Top-down”과 “Bottom-up”을 병행하면 기능을 빠르게 분할 가능.

---

OKR 요약

구분	목표	실행 방법
Objective	리뷰 가능한 PR 구조 확립	명확한 책임 범위 설정
KR1	PR 설명에 목적·범위 명시	Main purpose / Out-of-scope
KR2	PR 크기 최소화	기능 단위로 분할
KR3	대규모 기능은 단계적 구현	Top-down + Bottom-up 접근

---

Part 4. 리뷰 코멘트 처리 (Addressing Comments)

---

개념

“리뷰 코멘트에 단순히 반응하지 말고, 의도를 이해하고 확장하라.”

---

잘못된 반응

Reviewer: Please rename `doTask()` to `executeTask()`
Author: done ✅

→ 피드백을 기계적으로 수용만 함.

---

올바른 반응

Author: Updated to `executeTask()`.
Also applied the same rename to `cancelTask()` and `retryTask()` for consistency.

→ 리뷰 의도(일관성 향상) 를 이해하고, 다른 곳에도 적용함으로써 코드 전체 품질 향상 달성.

---

원칙

1. 코멘트의 핵심 아이디어 파악
2. 리뷰어의 질문이 생긴 이유 분석 (코드가 불명확했기 때문일 수도 있음)
3. 같은 개선점을 다른 코드에도 확장 적용

---

예제

if (userData == null) return // Reviewer: 왜 null check를 하는가?

// ✅ 개선 후
val isUserExpired = userData == null
if (isUserExpired) return

→ 의미 변수 도입으로 “왜 이 검사를 하는지” 명확히 표현.

---

Part 5. 리뷰어(Reviewer)의 역할과 태도

---

5-1. 기본 원칙

개념

리뷰는 “사람”이 아닌 “코드와 프로세스”를 평가하는 과정이다.

---

원칙

항목	내용
존중(Respect)	작성자에 대한 비난 금지, 코드만 평가
효율(Efficiency)	리뷰에 과도한 시간/자원 사용 금지
피드백 품질(Quality)	단순한 지적이 아니라 “왜 그런지” 설명
책임 분담(Accountability)	문제 PR은 즉시 반려, 방치 금지

---

5-2. 응답 및 일정 관리

리뷰 응답 예시

반응	좋음/나쁨	설명
“내일까지 확인할게요”	✅ Good	일정 공유
“지금은 바빠서 못 봅니다”	✅ Good	명확한 응답
“…” (무응답)	⚠️ Bad	리뷰 지연
“볼게요” 후 방치	🚫 Worst	팀 신뢰도 하락

---

원칙

• 리뷰 요청은 24시간 이내에 1차 응답
• 시간이 부족하면 “대체 리뷰어”를 지정하거나 일정 공유

---

5-3. 비효율적 리뷰 거부하기

잘못된 리뷰

• PR이 너무 크거나, 설계 문제부터 잘못된 경우

해결

• “구조만 남기고, 구현은 TODO로 작성해보세요.”
• 혹은 “기능별로 나눠서 두 번째 PR로 올려주세요.”

---

5-4. 마감 압박에 휘둘리지 않기

“데드라인은 품질 저하의 정당화 수단이 될 수 없다.”

• PR 승인을 서두르지 말고,
• 필요 시 명시적으로 “후속 보완 계획(TODO)”을 남겨라.

---

Part 6. 리뷰 코멘트 작성 원칙

---

개념

“무엇을 발견했는가”보다 “왜 그것이 중요한가” 를 전달하라.

---

리뷰 코멘트에 포함할 내용

• 코딩 스타일 / 컨벤션
• 로직, 예외, 성능 이슈
• 테스트 코드 포함 여부
• 기능과 설계의 복잡도 밸런스
• 가독성과 명명 규칙

---

예제

기존 코드

fun showPhotoView(photoData: PhotoData, isInEditScreen: Boolean) {
    if (!photoData.isValid) {
        if (isInEditScreen) showDialog()
        return
    }
    ...
}

---

✅ 개선 (리뷰 피드백 반영)

fun showPhotoView(photoData: PhotoData): Boolean {
    if (!photoData.isValid) return false
    ...
    return true
}

리뷰 포인트

• 불필요한 제어 결합(Control Coupling) 제거
• Boolean 반환으로 “성공/실패”를 명시
• “대화 상자 표시 여부”는 외부에서 제어하도록 분리

---

💬 리뷰어의 주석 예시

/**
 * Shows a photo if valid and returns true.
 * Otherwise returns false without showing the view.
 */
fun showPhotoView(photoData: PhotoData): Boolean

→ 함수의 의도와 결과가 명확해지고, 주석 일관성 유지.

---

Part 7. 리뷰 문화의 핵심

---

요약 원칙

항목	내용
Reviewee	작은 PR, 명확한 설명, 개선 의도 반영
Reviewer	존중, 효율적 피드백, 명확한 응답
공통	의도를 설명하고, 지식을 공유하는 문화

---

결론

코드 리뷰는 "코드 품질"이 아니라

“팀의 소통 품질”을 개선하는 행위다.

“좋은 코드”는 한 사람이 아니라

좋은 리뷰 문화에서 태어난다.

---

OKR 종합 요약

구분	목표	실행 방법	기대 효과
Objective	코드 리뷰를 통한 가독성·협업 품질 향상	리뷰 문화 확립	코드 품질 + 팀 생산성 향상
KR1	PR 설명에 목적과 범위 명시	리뷰 방향 명확화	리뷰 시간 단축
KR2	작은 PR로 리뷰 효율성 확보	Top-down / Bottom-up 병행	이해도 향상
KR3	리뷰 코멘트 의도 이해 후 확장 적용	코드 전반 품질 상승	반복 피드백 감소
KR4	리뷰어는 존중·효율·정확성 원칙 준수	신뢰도 있는 협업 문화	장기적 생산성 향상

---

핵심 결론

“가독성은 코드에서 시작해 리뷰로 완성된다.”

코드 리뷰는 “검열”이 아니라 “대화”이며, 좋은 리뷰는 좋은 코드보다 오래 남는다.

 

리뷰 코멘트를 작성자가 받아들이지 않을 때의 대처

1. 감정이 아니라 의도를 중심으로 대화하기
   • 리뷰 코멘트를 바로 거절하지 말고 “왜 그런 제안을 했는지” 먼저 묻는다.
   • 리뷰어도 “이건 틀렸다”보다는 “이렇게 하면 어떨까요?” 식으로 제안형으로 말한다.
2. 논리적 근거로 이야기하기
   • 개인 취향이 아니라 팀 컨벤션, 공식 문서, Lint 규칙 등을 근거로 제시한다.
   • “내 생각”이 아닌 “우리 기준”으로 대화하면 감정 충돌이 줄어든다.
3. 맥락을 설명하고 오해를 줄이기
   • 작성자는 “왜 이 코드를 이렇게 작성했는가”를 구체적으로 설명한다.
   • 리뷰어는 “그럼 이 부분의 리스크는 없을까요?”처럼 열린 질문으로 접근한다.
4. 논의가 길어지면 타임아웃 설정하기
   • PR에서 해결이 어렵다면 “다음 회의에서 결정하자”처럼 논의를 일단 종료한다.
   • 리뷰는 생산성 있는 협의가 목적이지, 토론의 승패가 아니다.
5. 필요할 땐 중재자 참여시키기
   • 시니어나 팀 리더가 객관적으로 기준을 제시하게 하여 합리적 결정을 내린다.
6. 결국 리뷰는 ‘설득’이 아니라 ‘공유’
   • 상대방을 이기려 하지 말고, 코드의 의도와 이유를 함께 이해하려는 태도가 중요하다.
   • 리뷰 충돌은 팀이 배우고 성장하는 기회로 삼는다.

리뷰 코멘트의 불일치는 “논리와 근거로 협의”하고, “감정이 아닌 협업의 언어”로 대화해야 한다.
리뷰의 목적은 옳고 그름이 아니라 합의와 성장이다.