Clean Code

1장. 클린 코드

이 책을 읽는 이유는 두 가지다. 첫째, 당신은 프로그래머다. 둘째, 더 나은 프로그래머가 되고 싶다. 좋다. 우리에게는 더 나은 프로그래머가 필요하다.

• 이 책은 좋은 프로그래밍에 관한 책이며, 코드로 가득 차 있음
• 코드를 위에서, 아래에서, 안에서 밖으로 다양한 방향으로 살펴봄
• 목표: 좋은 코드와 나쁜 코드를 구별하고, 좋은 코드를 작성하며, 나쁜 코드를 좋은 코드로 변환하는 방법을 익히는 것

코드는 사라지지 않는다

• “코드는 곧 사라질 것이다”는 주장에 대한 반박
  • 모델과 요구사항만 다루면 되고 코드는 더 이상 중요하지 않다는 시각이 존재함
  • 비즈니스 담당자가 명세서로 프로그램을 생성할 수 있게 되면 프로그래머가 필요 없어질 것이라는 전망도 있었음
• 코드는 절대 사라지지 않는다
  • 코드는 요구사항의 세부 내용을 표현하는 언어이기 때문
  • 기계가 실행할 수 있을 만큼 정밀하게 요구사항을 명세하는 행위 자체가 프로그래밍이며, 그 명세가 곧 코드
  • 추상화 수준이 높아지고 도메인 특화 언어(DSL)가 늘어나도, 그 언어로 작성된 명세 자체가 코드임
• 핵심 인사이트
  • 코드가 사라지길 바라는 사람들은 수학이 형식 없이도 존재하길 바라는 수학자와 같음
  • 인간조차 고객의 모호한 감정에서 성공적인 시스템을 만들어내지 못함
  • 잘 명세된 요구사항은 코드만큼 형식적이며, 그 자체로 코드의 실행 가능한 테스트가 될 수 있음
  • 필요한 정밀성은 절대 제거할 수 없다. 따라서 코드는 항상 존재할 것이다

나쁜 코드

• 나쁜 코드가 왜 중요한가
  • Kent Beck의 책 전제인 “좋은 코드는 중요하다”는 주장은 취약한 전제가 아니라, 우리 직종에서 가장 강력하고 지지받는 전제 중 하나
  • 우리는 좋은 코드가 중요하다는 것을 오랫동안 그 부재로 인해 겪으며 알게 되었음
• 나쁜 코드로 인한 회사 파멸 사례
  • 1980년대 후반, 한 회사가 킬러 앱을 개발해 큰 인기를 끌었음
  • 이후 릴리즈 주기가 늘어나고, 버그가 수정되지 않으며, 로드 시간이 길어지고 크래시가 증가
  • 결국 회사는 폐업했고, 원인은 시장 출시를 서두르다 코드를 엉망으로 만들었기 때문
  • 기능을 추가할수록 코드는 점점 더 나빠져 더 이상 관리할 수 없게 됨
• Wading(허우적거림)
  • 나쁜 코드를 헤쳐나가는 것을 “wading”이라 부름
  • 뒤엉킨 수풀과 숨겨진 함정을 헤쳐나가며 방향을 찾으려 애쓰는 것과 같음
• 나쁜 코드를 작성하는 이유
  • 빠르게 처리하려는 조급함
  • 상사의 눈치
  • 프로그램 작업에 지쳐서
  • 다른 할 일이 밀려 있어서
  • LeBlanc의 법칙: 나중은 결코 오지 않는다 (Later equals never)

엉망인 코드의 총비용

• 엉망인 코드의 총 비용
  • 경력 2~3년 이상이라면 타인의 지저분한 코드 때문에 상당히 지체된 경험이 있음
  • 프로젝트 초반에 빠르게 진행되던 팀이 1~2년 후에는 거의 정지 상태에 빠지는 경우가 흔함
  • 코드 변경 하나가 다른 두세 곳을 망가뜨림 → 사소한 변경이 없어짐
  • 엉킴과 뒤틀림을 이해하지 않고서는 아무것도 추가·수정 불가능
• 생산성의 점진적 붕괴

graph LR
    A[엉망인 코드 누적] --> B[팀 생산성 감소]
    B --> C[관리자: 인력 추가]
    C --> D[새 인력: 설계 의도 파악 불가]
    D --> E[더 많은 엉망 코드 생성]
    E --> A

• 생산성은 시간이 지남에 따라 점근적으로 0에 가까워짐
• 관리자는 인력을 추가하지만, 새 인력은 시스템 설계를 이해하지 못함
• 결과적으로 더 많은 엉망을 만들어내며 생산성을 더욱 낮춤

하늘 위의 대규모 재설계

• 대규모 재설계의 함정
  • 결국 팀은 반발하여 전면 재설계를 요구함
  • 관리자는 자원 낭비를 원치 않지만 생산성 붕괴를 부정할 수 없어 결국 승인
• 타이거 팀(Tiger Team)의 딜레마
  • 새로운 타이거 팀 구성 → 모두가 이 그린필드 프로젝트에 합류하고 싶어 함
  • 이 팀은 기존 시스템이 하는 모든 것을 새 시스템으로 구현해야 함
  • 동시에 기존 시스템에 지속적으로 추가되는 변경 사항도 따라잡아야 함
  • 이 경쟁은 10년씩 이어지기도 함
  • 결말: 타이거 팀의 원년 멤버들이 모두 떠난 뒤, 새 멤버들이 “이 새 시스템도 엉망”이라며 또 재설계를 요구하게 됨
• 핵심 교훈
  • 코드를 깨끗하게 유지하는 데 시간을 쓰는 것은 비용 효율적인 것을 넘어 전문가적 생존의 문제

태도

• 코드가 썩는 이유는 우리 자신에게 있다
  • 요구사항 변경, 빡빡한 일정, 어리석은 관리자, 고객을 탓하지만 → 결국 우리가 비전문적으로 행동한 것
  • 관리자와 마케터는 우리에게 정보를 의존함. 우리가 말하지 않으면 그들은 모름
  • 의사가 수술 전 손 씻기를 환자가 “시간 낭비”라고 요청해도 거부해야 하듯이, 프로그래머도 엉망을 만드는 것의 위험성을 이해하지 못하는 관리자의 뜻에 굴복해서는 안 됨

근본적 딜레마

• 프로그래머가 직면하는 근본적인 딜레마
  • 경험 있는 개발자라면 누구나 알고 있음: 이전의 엉망이 자신을 느리게 만든다
  • 그럼에도 마감을 맞추기 위해 엉망을 만들어야 한다는 압박을 느낌
• 진짜 전문가의 인식
  • 엉망을 만들어서 마감을 맞출 수 없음
  • 오히려 엉망은 즉시 속도를 늦추고, 마감을 놓치게 만듦
  • 마감을 맞추는 유일한 방법 = 항상 코드를 최대한 깨끗하게 유지하는 것

클린 코드의 예술

• 클린 코드 작성은 예술이다
  • 그림을 잘 그렸는지 나쁘게 그렸는지 아는 것이 그림을 잘 그릴 수 있음을 의미하지 않음
  • 클린 코드를 식별할 수 있다고 해서 클린 코드를 작성할 수 있다는 의미가 아님
• code-sense (코드 감각)
  • 클린 코드 작성에는 수많은 작은 기술들의 훈련된 사용과 고통스럽게 터득한 청결함에 대한 감각이 필요
  • 일부는 타고나고, 일부는 싸워서 얻어야 함
  • code-sense가 없는 프로그래머: 엉망을 인식하지만 어떻게 해야 할지 모름
  • code-sense가 있는 프로그래머: 엉망을 보고 옵션과 변형을 발견하며, 동작을 보존하는 일련의 변환 순서를 계획함
  • 클린 코드를 작성하는 프로그래머는 빈 화면을 우아하게 코딩된 시스템으로 변환하는 예술가

클린 코드란 무엇인가

저명한 프로그래머들이 정의한 클린 코드의 의미를 정리하면 다음과 같다.

C++ 창시자(Bjarne Stroustrup)

우아하고 효율적인 코드를 좋아한다. 논리는 버그가 숨기 어렵도록 간단해야 하고, 의존성은 유지보수를 쉽게 하기 위해 최소화해야 하며, 에러 처리는 명확한 전략에 따라 완전해야 하고, 성능은 최적에 가까워야 한다. 클린 코드는 한 가지를 잘 한다.

• 우아함(Elegant): 읽을 때 기쁨을 주어야 함. 잘 만들어진 뮤직박스나 잘 설계된 차처럼
• 효율성: 낭비된 사이클은 우아하지 않으며, 나쁜 코드는 엉망이 더 커지도록 유혹함 (broken windows 이론)
• 완전한 에러 처리: 세부 사항에 주의를 기울이는 규율. 메모리 누수, 경쟁 조건, 일관성 없는 네이밍 모두 세부 사항에 소홀한 증거
• 단일 집중: 각 함수, 클래스, 모듈은 주변 세부 사항에 흐트러지지 않고 한 가지 태도를 유지해야 함

OOA&D 저자(Grady Booch)

클린 코드는 단순하고 직접적이다. 클린 코드는 잘 쓴 산문처럼 읽힌다. 클린 코드는 설계자의 의도를 절대 숨기지 않으며, 오히려 명확한 추상화와 직선적인 제어 흐름으로 가득 차 있다.

• 가독성 관점: 좋은 소설을 읽을 때 단어가 사라지고 이미지가 떠오르듯, 클린 코드도 읽으면서 문제의 긴장감이 명확하게 드러나야 함
• crisp abstraction(명확한 추상화): 코드는 추측이 아닌 사실 위주여야 하며, 필요한 것만 담고 독자가 결단력 있음을 느껴야 함

OTI 창립자(“Big” Dave Thomas)

클린 코드는 원작자 이외의 개발자도 읽고 개선할 수 있다. 단위 테스트와 인수 테스트가 있다. 의미 있는 이름을 가진다. 한 가지를 하는 방법을 여러 개가 아닌 하나만 제공한다. 최소한의 의존성을 가지며, 명확하고 최소한의 API를 제공한다.

• 읽기 쉬운 코드 vs 변경하기 쉬운 코드의 차이를 강조
• 테스트와 클린 코드의 연결: 테스트가 없으면 클린 코드가 아님. 아무리 우아하고 읽기 쉬워도 테스트 없이는 불결함
• 최소성: 작은 코드가 큰 코드보다 낫다
• 리터러시: Knuth의 리터러트 프로그래밍 참조 — 코드는 인간이 읽을 수 있는 형태로 구성되어야 함

Working Effectively with Legacy Code 저자(Michael Feathers)

클린 코드의 모든 품질을 나열할 수 있지만, 그것들로 이어지는 하나의 핵심 품질이 있다. 클린 코드는 항상 누군가가 신경 쓴 것처럼 보인다. 더 나아지게 할 수 있는 명백한 것이 아무것도 없다.

• 핵심 단어: Care(배려)
  • 클린 코드는 누군가가 단순하고 질서 있게 유지하기 위해 시간을 쓴 코드
  • 세부 사항에 적절한 주의를 기울인 코드
  • 이 책의 적절한 부제는 “How to Care for Code”

Extreme Programming 저자(Ron Jeffries)

Beck의 단순한 코드 규칙을 우선순위 순서로:

1. 모든 테스트를 통과한다
2. 중복이 없다
3. 시스템의 모든 설계 아이디어를 표현한다
4. 클래스, 메서드, 함수 등의 엔티티 수를 최소화한다

• 중복 제거가 핵심
  • 같은 것이 반복된다면, 코드에 잘 표현되지 않은 아이디어가 머릿속에 있다는 신호
  • 그 아이디어를 찾아내고 더 명확하게 표현해야 함
• 표현력(Expressiveness)
  • 의미 있는 이름 포함
  • 객체나 메서드가 두 가지 이상을 하는지 확인
  • 메서드가 두 가지를 한다면 Extract Method 리팩토링으로 분리
• 컬렉션 추상화 예시

// 나쁜 예: 구체적인 구현에 직접 의존
const employees = new Map<string, Employee>();
const found = employees.get("john");

// 좋은 예: 추상화로 감싸서 구현 변경의 자유를 얻음
class EmployeeRepository {
  private store = new Map<string, Employee>();

  findById(id: string): Employee | undefined {
    return this.store.get(id);
  }
}

• Ron의 요약: 중복 감소 + 높은 표현력 + 단순 추상화의 조기 구축 = 클린 코드

Wiki·eXtreme Programming 공동 창시자(Ward Cunningham)

각 루틴을 읽을 때 거의 예상한 대로인 경우 클린 코드에서 작업하고 있다는 것을 알 수 있다. 코드가 마치 그 문제를 위해 언어가 만들어진 것처럼 보일 때 아름다운 코드라고 부를 수 있다.

• 놀라움이 없는 코드: 읽을 때 노력이 필요 없고, 명백하고 단순하며 설득력 있음
• 아름다운 코드: 언어가 그 문제를 위해 만들어진 것처럼 보이게 함
  • 언어를 단순하게 만드는 것은 언어 자체가 아니라 프로그래머의 책임

학파와 관점

• Uncle Bob(저자)의 입장
  • 이 책은 클린 변수명, 클린 함수, 클린 클래스 등에 대해 Object Mentor 학파의 관점을 제시함
  • 이 견해들을 절대적인 것으로 제시하지만, 이것이 절대적으로 옳다는 의미는 아님
• 무술 학파 비유
  • 다양한 무술 유파(Gracie Jiu Jitsu, Hakkoryu Jiu Jitsu, Jeet Kune Do)가 있듯이, 클린 코드에 대한 다양한 학파가 있음
  • 하나의 학파 내에서 올바른 방법이 있더라도, 그것이 다른 학파를 무효화하지 않음
  • 이 책의 가르침을 따르되, 다른 학파와 대가들로부터도 배울 것을 권장
• 이 책의 추천 사항들 중 일부는 논쟁의 여지가 있음
  • 모든 것에 동의하지 않아도 됨
  • 하지만 수십 년의 경험과 반복된 시행착오를 통해 터득한 관점을 존중해 달라

우리는 저자다

• 우리는 저자다
  • Javadoc의 @author 필드가 우리가 누구인지 알려줌
  • 저자에게는 독자가 있으며, 저자는 독자와 잘 소통할 책임이 있음
  • 코드 한 줄을 작성할 때마다 자신의 노력을 평가할 독자를 위해 쓰는 저자임을 기억해야 함
• 코드는 쓰는 것보다 읽는 시간이 훨씬 많다
  • 코드를 읽는 시간 대 쓰는 시간의 비율: 10:1 이상
  • 새 코드를 작성하는 노력의 일부로 항상 기존 코드를 읽고 있음
• 읽기 쉬운 코드가 쓰기도 쉽다
  • 주변 코드를 읽지 않고서는 새 코드를 작성할 수 없음
  • 오늘 작성하려는 코드가 어렵거나 쉬운 것은 주변 코드가 읽기 어렵거나 쉬운지에 달려 있음
  • 빠르게 진행하고 싶다면, 읽기 쉽게 만들어라

보이스카우트 규칙

• 보이스카우트 규칙

캠프장을 발견했을 때보다 더 깨끗하게 떠나라.

• 코드를 체크아웃할 때보다 조금 더 깨끗하게 체크인하면, 코드는 절대 썩지 않음
• 청소는 크게 할 필요 없음:
  • 변수명 하나를 더 낫게 바꾸기
  • 너무 큰 함수 하나를 나누기
  • 중복된 코드 조각 하나를 제거하기
  • 복합 if 문 하나를 정리하기
• 지속적 개선은 프로페셔널리즘의 본질적인 부분

전사와 원칙

• 이 책은 2002년에 저자가 쓴 Agile Software Development: Principles, Patterns, and Practices(PPP) 의 “프리퀄”
• PPP는 객체 지향 설계 원칙과 전문 개발자들이 사용하는 실천 방법을 다룸
• 이 책에서 등장하는 설계 원칙들:
  • SRP (Single Responsibility Principle, 단일 책임 원칙)
  • OCP (Open Closed Principle, 개방 폐쇄 원칙)
  • DIP (Dependency Inversion Principle, 의존성 역전 원칙)

정리

• 예술 책이 예술가를 만들어주지 않듯, 이 책도 좋은 프로그래머를 만들어주겠다고 약속하지 않음
• 이 책이 할 수 있는 것: 좋은 프로그래머들의 사고 과정, 기술, 도구를 보여주는 것
• 결국은 연습뿐이다

“Carnegie Hall에 어떻게 가나요?“라고 물었을 때 노인이 대답했다: “연습, 아들아. 연습!”

핵심 요약

• 코드의 존재: 코드는 사라지지 않는다. 정밀성을 제거할 수 없기 때문
• 나쁜 코드의 비용: 생산성을 점근적으로 0으로 낮추며, 회사를 망하게 할 수 있음
• 책임: 코드 품질에 대한 책임은 관리자가 아닌 프로그래머에게 있음
• 진짜 속도: 빠르게 가는 유일한 방법은 항상 코드를 깨끗하게 유지하는 것
• code-sense: 나쁜 코드를 인식하는 것을 넘어 어떻게 고칠지 아는 감각
• 저자 의식: 코드는 읽는 시간이 쓰는 시간의 10배. 독자를 위해 써라
• 보이스카우트 규칙: 발견했을 때보다 조금 더 깨끗하게 남겨라

2장. 의미 있는 이름

이름은 소프트웨어 어디에나 있다. 변수, 함수, 인수, 클래스, 패키지, 소스 파일, 디렉터리, jar/war/ear 파일까지. 우리는 끊임없이 이름을 짓는다. 그러니 잘 짓는 편이 낫다.

의도를 드러내는 이름을 사용하라

• 이름은 존재 이유, 수행 기능, 사용 방법이라는 세 가지 질문에 모두 답해야 함
• 이름에 주석이 필요하다면, 그 이름은 의도를 드러내지 못하는 것
• 좋은 이름을 고르는 데는 시간이 걸리지만, 절약되는 시간이 훨씬 더 많음
• 더 좋은 이름이 떠오르면 언제든 바꿔라. 코드를 읽는 모두가 행복해진다

나쁜 예:

const d: number; // 경과 시간(일 단위)

좋은 예:

const elapsedTimeInDays: number;
const daysSinceCreation: number;
const daysSinceModification: number;
const fileAgeInDays: number;

코드 가독성 비교 — 지뢰찾기 게임 예시:

// 나쁜 예: 암묵적인 코드 (무엇을 하는지 알 수 없음)
function getThem(): number[][] {
  const list1: number[][] = [];
  for (const x of theList) {
    if (x[0] === 4) list1.push(x);
  }
  return list1;
}

// 좋은 예: 의도가 드러나는 코드
function getFlaggedCells(): Cell[] {
  const flaggedCells: Cell[] = [];
  for (const cell of gameBoard) {
    if (cell.isFlagged()) flaggedCells.push(cell);
  }
  return flaggedCells;
}

• 코드의 복잡성은 그대로지만, 이름만 바꿔도 무엇을 하는지 즉시 이해 가능
• 핵심: 코드의 단순성이 아닌 암묵성(implicity) 이 문제다. 컨텍스트가 코드 안에 명시되어야 한다

잘못된 정보를 피하라

• 거짓 단서를 남기지 마라 — 코드의 의미를 흐리는 잘못된 정보는 독자를 혼란에 빠뜨림
• 플랫폼 이름이나 특수 의미를 가진 단어를 변수명으로 쓰지 말 것 (예: hp, aix, sco)
• 컨테이너 타입을 이름에 인코딩하지 마라
  • 실제로 List가 아닌데 accountList라고 부르면 잘못된 정보를 제공하는 것
  • accountGroup, bunchOfAccounts, 또는 그냥 accounts가 더 나음
• 미세하게 다른 이름을 피하라
  • XYZControllerForEfficientHandlingOfStrings와 XYZControllerForEfficientStorageOfStrings의 차이를 금방 눈치채기 어려움
• 소문자 l과 대문자 O를 변수명으로 절대 사용하지 마라
  • 각각 숫자 1과 0처럼 보여 극심한 혼란 유발

// 최악의 예: 1과 0인지 l과 O인지 구분이 불가능
let a = l;
if (O == l) a = O1;
else l = 01;

의미 있게 구분하라

• 컴파일러만 통과시키기 위한 임의적 이름 변경은 금물
  • 이름이 달라야 한다면 의미도 달라야 함
• 숫자 연속 이름(a1, a2, …aN)은 의미가 없음
  • 비정보적(noninformative)이며 작성자의 의도를 전혀 전달하지 않음

// 나쁜 예
function copyChars(a1: string[], a2: string[]): void { ... }

// 좋은 예
function copyChars(source: string[], destination: string[]): void { ... }

• 노이즈 워드(noise word)는 의미 없는 구분이다
  • Product, ProductInfo, ProductData — Info와 Data는 아무 의미도 추가하지 않음
  • a, an, the 같은 접두어도 맥락 없이 쓰면 노이즈
• 중복 표현을 제거하라
  • 변수명에 variable이라는 단어를 넣지 마라
  • 테이블명에 table이라는 단어를 넣지 마라
  • NameString이 Name보다 나을 게 없다

혼동을 주는 나쁜 예:

getActiveAccount();
getActiveAccounts();
getActiveAccountInfo();
// 어떤 것을 호출해야 할지 알 수 없음

발음할 수 있는 이름을 사용하라

• 인간의 뇌는 언어를 위해 설계되어 있다. 발음 가능한 이름을 활용하라
• 발음할 수 없는 이름은 코드를 논의할 때 바보처럼 만든다
• 프로그래밍은 사회적 활동이다

// 나쁜 예: 발음 불가능한 이름
class DtaRcrd102 {
  private genymdhms: Date;
  private modymdhms: Date;
  private readonly pszqint: string = "102";
}

// 좋은 예: 발음 가능한 이름
class Customer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private readonly recordId: string = "102";
}

• 좋은 이름: “이봐, 이 레코드 좀 봐! 생성 타임스탬프가 내일 날짜로 설정되어 있어!” 라고 자연스럽게 대화 가능

검색하기 쉬운 이름을 사용하라

• 단일 문자 이름과 숫자 상수는 검색하기 어렵다
  • MAX_CLASSES_PER_STUDENT는 grep으로 쉽게 찾을 수 있지만, 숫자 7은 여러 곳에서 등장해 찾기 어려움
  • 문자 e는 영어에서 가장 자주 사용되는 글자 — 변수명으로 최악의 선택
• 이름의 길이는 스코프의 크기에 비례해야 한다
  • 짧은 메서드 안의 루프 카운터(i, j, k)는 예외적으로 단일 문자 사용 가능
  • 여러 곳에서 사용되는 변수나 상수는 반드시 검색 친화적 이름을 부여할 것

// 나쁜 예: 숫자가 무엇을 의미하는지 알 수 없음
for (let j = 0; j < 34; j++) {
  s += (t[j] * 4) / 5;
}

// 좋은 예: 검색 가능하고 의미 있는 이름
const REAL_DAYS_PER_IDEAL_DAY = 4;
const WORK_DAYS_PER_WEEK = 5;
const NUMBER_OF_TASKS = 34;
let sum = 0;

for (let j = 0; j < NUMBER_OF_TASKS; j++) {
  const realTaskDays = taskEstimate[j] * REAL_DAYS_PER_IDEAL_DAY;
  const realTaskWeeks = realTaskDays / WORK_DAYS_PER_WEEK;
  sum += realTaskWeeks;
}

• WORK_DAYS_PER_WEEK를 검색하는 것이 5를 검색하고 필터링하는 것보다 훨씬 쉬움

인코딩을 피하라

• 타입이나 스코프 정보를 이름에 인코딩하면 해독 부담이 늘어남
• 새 개발자는 코드 자체를 배우는 것도 벅찬데, 인코딩 규칙까지 외워야 함
• 인코딩된 이름은 발음하기 어렵고 오타 발생 가능성이 높음

헝가리식 표기법

• 과거 컴파일러가 타입을 기억하지 못하던 시절의 유산
• 현대 언어와 IDE는 타입 오류를 컴파일 전에 잡아준다 — HN은 이제 방해물일 뿐
• 타입이 변경되어도 이름은 그대로 남아 잘못된 정보를 제공하게 됨

// 나쁜 예: 타입이 변경되었지만 이름은 그대로
let phoneString: PhoneNumber; // 타입이 string에서 PhoneNumber로 바뀌었지만 이름은 여전히 String

멤버 접두어

• m_ 접두어는 더 이상 필요 없다
• 클래스와 함수를 충분히 작게 유지하면 멤버 변수를 구분하는 접두어가 필요 없음
• 코드를 많이 읽을수록 접두어는 점점 보이지 않게 되고, 결국 구식 코드의 표식이 됨

// 나쁜 예
class Part {
  private m_dsc: string; // 텍스트 설명
  setName(name: string): void {
    this.m_dsc = name;
  }
}

// 좋은 예
class Part {
  private description: string;
  setDescription(description: string): void {
    this.description = description;
  }
}

인터페이스와 구현

• 인터페이스에 I 접두어를 붙이지 마라
  • IShapeFactory는 주의를 분산시키며 과도한 정보를 제공함
  • 사용자는 인터페이스를 받는다는 사실을 굳이 알 필요가 없음
• 인코딩이 필요하다면 구현 클래스에 붙여라

정신적 매핑을 피하라

• 독자가 자신이 아는 이름으로 변환해야 하는 이름은 나쁜 이름
• 루프 카운터 i, j, k는 전통적으로 허용되지만, 단 l은 절대 안 됨
• 그 외의 단일 문자 이름은 독자가 실제 개념으로 정신적 매핑을 강요하는 자리 표시자일 뿐
• r이 호스트와 스킴을 제거한 소문자 URL이라는 걸 기억한다고 해서 영리한 게 아니다

스마트한 프로그래머와 전문적인 프로그래머의 차이: 전문가는 명확성이 왕이라는 것을 이해한다. 전문가는 능력을 선하게 사용하여 다른 사람이 이해할 수 있는 코드를 작성한다.

클래스 이름

• 클래스와 객체는 명사 또는 명사구로 이름을 지어야 함
  • 좋은 예: Customer, WikiPage, Account, AddressParser
• 동사는 클래스 이름으로 부적절
• 피해야 할 단어: Manager, Processor, Data, Info
  • 이런 단어는 아무 의미도 추가하지 않고 범용적으로 쓰여 혼란을 유발

메서드 이름

• 메서드는 동사 또는 동사구로 이름을 지어야 함
  • 좋은 예: postPayment, deletePage, save
• 접근자, 변경자, 조건자는 값 앞에 get, set, is를 붙임 (javabean 표준)

const name = employee.getName();
customer.setName("mike");
if (paycheck.isPosted()) { ... }

• 생성자 오버로드 시, 인수를 설명하는 이름의 정적 팩터리 메서드를 사용하라

// 나쁜 예
const fulcrumPoint = new Complex(23.0);

// 좋은 예: 인수가 무엇인지 이름에서 드러남
const fulcrumPoint = Complex.fromRealNumber(23.0);

• 해당 생성자를 private으로 선언하여 정적 팩터리 메서드 사용을 강제하는 것도 고려할 것

귀엽게 짓지 마라

• 재치 있는 이름은 작성자의 유머를 공유하는 사람만 기억함
  • HolyHandGrenade가 무엇을 하는지 알 수 있는가? DeleteItems가 훨씬 낫다
  • whack() 대신 kill(), eatMyShorts() 대신 abort()를 사용하라
• 은어나 문화 의존적 농담을 코드에 넣지 마라
• 엔터테인먼트 가치보다 명확성을 선택하라

말하는 바를 코드로 써라. 코드로 쓴 것이 곧 말하는 바다.

개념당 단어 하나를 선택하라

• 하나의 추상 개념에는 하나의 단어를 선택하고 일관되게 사용하라
  • fetch, retrieve, get을 서로 다른 클래스에서 같은 의미로 사용하면 혼란
  • 어떤 클래스가 어떤 메서드 이름을 쓰는지 기억해야 하는 부담이 생김
• 같은 코드베이스에 controller, manager, driver가 혼재하면 혼란
  • DeviceManager와 ProtocolController의 본질적 차이는 무엇인가?
• 일관된 어휘는 코드를 사용하는 프로그래머에게 큰 선물이다

말장난을 하지 마라

• 같은 단어를 두 가지 목적으로 사용하지 마라 — 이는 일종의 말장난(pun)
• add가 두 값을 더하거나 이어붙이는 맥락에서 사용되던 클래스들이 있을 때, 단일 값을 컬렉션에 삽입하는 새 메서드도 add라고 부르면 말장난이 됨
  • 이 경우는 insert 또는 append가 올바른 선택
• “one word per concept” 원칙과 충돌하더라도, 의미가 다르면 이름도 달라야 한다

우리의 목표는 코드를 깊이 연구해야 하는 학술 논문이 아니라, 빠르게 훑어볼 수 있는 대중 소설처럼 읽히는 코드를 만드는 것이다. 저자가 독자에게 명확하게 설명할 책임이 있다.

솔루션 도메인 이름을 사용하라

• 코드를 읽는 사람은 프로그래머다 — CS 용어, 알고리즘 이름, 패턴 이름, 수학 용어를 적극 활용하라
• 모든 이름을 문제 도메인에서 가져오면, 동료가 고객에게 매번 의미를 확인해야 하는 상황 발생
  • AccountVisitor — VISITOR 패턴을 아는 프로그래머에게 즉시 의미가 전달됨
  • JobQueue — 모든 프로그래머가 이해하는 기술 용어

문제 도메인 이름을 사용하라

• 적절한 프로그래밍 용어가 없다면 문제 도메인의 이름을 사용하라
  • 코드를 유지보수하는 프로그래머가 도메인 전문가에게 의미를 물어볼 수 있음
• 솔루션 도메인과 문제 도메인 개념을 구분하는 것은 좋은 프로그래머와 설계자의 역할
• 문제 도메인 개념에 가까운 코드는 문제 도메인에서 이름을 가져와야 함

의미 있는 맥락을 추가하라

• 대부분의 이름은 그 자체만으로는 의미가 충분하지 않다
  • 잘 이름 붙여진 클래스, 함수, 네임스페이스 안에 이름을 배치하여 맥락을 제공해야 함
• firstName, lastName, street, city, state, zipCode는 함께 놓이면 주소임을 알 수 있음
  • 하지만 state 단독으로 사용되면 주소의 일부임을 알기 어려움
• 접두어로 맥락 추가: addrFirstName, addrState 등으로 더 큰 구조의 일부임을 암시
• 더 나은 방법: 클래스를 생성하라 — Address 클래스를 만들면 컴파일러도 이 변수들이 더 큰 개념에 속함을 알게 됨

맥락이 불명확한 코드 예시 (리팩터링 전):

function printGuessStatistics(candidate: string, count: number): void {
  let number: string;
  let verb: string;
  let pluralModifier: string;

  if (count === 0) {
    number = "no";
    verb = "are";
    pluralModifier = "s";
  } else if (count === 1) {
    number = "1";
    verb = "is";
    pluralModifier = "";
  } else {
    number = count.toString();
    verb = "are";
    pluralModifier = "s";
  }

  const guessMessage = `There ${verb} ${number} ${candidate}${pluralModifier}`;
  print(guessMessage);
}

맥락이 명확한 코드 예시 (리팩터링 후):

class GuessStatisticsMessage {
  private number: string = "";
  private verb: string = "";
  private pluralModifier: string = "";

  make(candidate: string, count: number): string {
    this.createPluralDependentMessageParts(count);
    return `There ${this.verb} ${this.number} ${candidate}${this.pluralModifier}`;
  }

  private createPluralDependentMessageParts(count: number): void {
    if (count === 0) this.thereAreNoLetters();
    else if (count === 1) this.thereIsOneLetter();
    else this.thereAreManyLetters(count);
  }

  private thereAreManyLetters(count: number): void {
    this.number = count.toString();
    this.verb = "are";
    this.pluralModifier = "s";
  }

  private thereIsOneLetter(): void {
    this.number = "1";
    this.verb = "is";
    this.pluralModifier = "";
  }

  private thereAreNoLetters(): void {
    this.number = "no";
    this.verb = "are";
    this.pluralModifier = "s";
  }
}

• GuessStatisticsMessage 클래스로 분리함으로써 세 변수의 맥락이 명확해짐
• 알고리즘도 더 작은 함수들로 분리되어 훨씬 깔끔해짐

불필요한 맥락을 추가하지 마라

• 필요 이상의 맥락을 이름에 추가하지 마라
  • “Gas Station Deluxe” 앱에서 모든 클래스 앞에 GSD를 붙이는 것은 나쁜 생각
  • G를 입력하고 자동완성을 누르면 시스템의 모든 클래스가 나열됨
• 짧은 이름이 긴 이름보다 낫다 — 단, 명확한 경우에 한해서
• 이름에 필요한 맥락만 추가하라

예시:

// GSDAccountAddress — 17자 중 10자가 불필요하거나 무관한 정보
// 고객 연락 앱에서 재사용하기 어려운 이름

// Address — 깔끔하고 재사용 가능한 클래스 이름
// 구분이 필요할 때는 구체적으로:
class PostalAddress { ... }   // 우편 주소
class MacAddress { ... }      // MAC 주소
class URI { ... }             // 웹 주소

• 인스턴스명으로 accountAddress, customerAddress는 적절하나, 클래스명으로는 부적절
• 정밀성이 목적이다. 필요한 만큼만 구체적으로 이름을 지어라

정리

• 좋은 이름을 선택하는 것은 좋은 묘사 능력과 공유된 문화적 배경을 필요로 함
• 기술적, 비즈니스적 문제가 아닌 교육의 문제
• 많은 개발자들이 다른 개발자의 반발을 두려워해 이름 바꾸기를 꺼림
  • 하지만 이름이 (좋은 방향으로) 바뀌면 오히려 감사하게 됨
• 현대 도구들 덕분에 클래스와 메서드의 이름을 외울 필요가 없음 — 코드가 문단과 문장처럼 읽히는지에 집중하라
• 두려워하지 말고 리네임(rename)하라. 다른 코드 개선과 마찬가지로, 누군가를 놀라게 할 수 있지만 그것이 멈춰야 할 이유가 되지 않는다

핵심 요약

• 의도를 드러내는 이름: 이름은 왜 존재하는지, 무엇을 하는지, 어떻게 쓰는지를 답해야 한다
• 잘못된 정보 회피: 거짓 단서, 유사한 이름, l/O 같은 혼동 문자를 피하라
• 의미 있는 구분: 이름이 다르면 의미도 달라야 한다. 노이즈 워드는 제거하라
• 발음 가능한 이름: 대화에서 자연스럽게 사용할 수 있는 이름을 선택하라
• 검색 가능한 이름: 단일 문자와 매직 넘버는 grep이 불가능하다. 스코프가 크면 이름도 길게
• 인코딩 회피: HN, m_ 접두어, I 접두어는 현대 개발 환경에서 불필요한 짐이다
• 정신적 매핑 회피: 독자가 이름을 다른 개념으로 번역하게 만들지 마라
• 클래스는 명사: Manager/Processor/Data/Info를 피하고, 명확한 명사를 사용하라
• 메서드는 동사: get/set/is 접두어를 활용하고, 팩터리 메서드에 의도 담기
• 귀엽지 않게: 유머보다 명확성을 선택하라
• 개념당 단어 하나: fetch/retrieve/get을 혼용하지 말고 하나를 일관되게 사용하라
• 말장난 금지: 의미가 다른 개념에 같은 단어를 쓰지 마라
• 솔루션 도메인 이름: CS 용어, 패턴 이름 등 프로그래머가 이미 아는 단어를 활용하라
• 문제 도메인 이름: 적절한 기술 용어가 없으면 도메인 용어를 사용하라
• 맥락 추가: 이름을 클래스/함수 안에 배치하거나, 클래스를 만들어 맥락을 부여하라
• 불필요한 맥락 금지: 짧고 명확한 이름이 길고 중복된 이름보다 낫다

3장. 함수

함수는 모든 프로그램에서 조직의 첫 번째 단위다. 함수를 잘 작성하는 것이 이 챕터의 주제다.

들어가며

• 프로그래밍 초창기에는 루틴과 서브루틴으로 시스템을 구성했고, Fortran/PL1 시대에는 프로그램·서브프로그램·함수로 구성했음
• 오늘날에는 함수만이 살아남았으며, 함수는 모든 프로그램에서 조직의 첫 번째 단위
• 나쁜 함수의 특징: 길이가 길고, 중복된 코드, 의미 없는 문자열, 이해하기 어려운 데이터 타입과 API가 뒤섞임
• 몇 가지 간단한 메서드 추출, 이름 변경, 구조 개선만으로도 의도를 명확하게 전달하는 함수로 바꿀 수 있음

함수는 작게

• 함수의 첫 번째 규칙: 작아야 한다
• 함수의 두 번째 규칙: 그것보다 더 작아야 한다
• 수십 년간의 경험이 가르쳐 준 진실: 함수는 매우 작아야 한다
• 과거에는 VT100 터미널 기준으로 “화면 한 페이지” 크기를 기준으로 삼았으나 현재는 무의미
• 한 줄에 150자, 함수에 100줄이 들어가는 모니터도 있지만, 그렇다고 그만큼 길게 써도 된다는 의미가 아님
• 이상적인 함수의 길이: 2~4줄. 각 함수가 하나의 이야기를 명확하게 말해줘야 함

// 나쁜 예: 너무 많은 일을 하는 긴 함수
async function testableHtml(pageData: PageData, includeSuiteSetup: boolean): Promise<string> {
  const wikiPage = pageData.getWikiPage();
  const buffer: string[] = [];

  if (pageData.hasAttribute("Test")) {
    if (includeSuiteSetup) {
      const suiteSetup = PageCrawlerImpl.getInheritedPage(SuiteResponder.SUITE_SETUP_NAME, wikiPage);
      if (suiteSetup !== null) {
        const pagePath = suiteSetup.getPageCrawler().getFullPath(suiteSetup);
        const pagePathName = PathParser.render(pagePath);
        buffer.push(`!include -setup .${pagePathName}\n`);
      }
    }
    // ... 수십 줄 더 이어짐
  }
  return pageData.getHtml();
}

// 좋은 예: 리팩토링 후
async function renderPageWithSetupsAndTeardowns(pageData: PageData, isSuite: boolean): Promise<string> {
  if (await isTestPage(pageData))
    await includeSetupAndTeardownPages(pageData, isSuite);
  return pageData.getHtml();
}

블록과 들여쓰기

• if, else, while 등의 블록 내부는 한 줄이어야 하며, 그 줄은 함수 호출이어야 함
  • 바깥 함수를 작게 유지하고, 블록 내 함수에 서술적인 이름을 붙여 문서화 효과를 얻음
• 함수는 중첩 구조를 가질 만큼 커서는 안 됨
• 함수의 들여쓰기 수준은 1~2단계를 넘지 않아야 함
• 이렇게 하면 함수를 읽고 이해하기 훨씬 쉬워짐

한 가지만 해라

함수는 한 가지를 해야 한다. 그것을 잘 해야 한다. 그것만 해야 한다.

• “한 가지”란 무엇인가? — 함수 이름보다 한 단계 아래 수준의 작업들만 수행하는 것
• 함수가 하나의 작업만 하는지 확인하는 방법: TO 문단으로 설명해보기
  • 예: “TO renderPageWithSetupsAndTeardowns, 테스트 페이지인지 확인하고, 맞으면 setup/teardown을 포함한 후, HTML로 렌더링한다”
  • 이 설명에서 각 단계가 함수 이름의 바로 아래 수준 추상화라면 단일 책임을 지키는 것
• 다른 함수를 의미 있게 추출할 수 있다면, 그 함수는 여러 가지를 하고 있는 것

함수 내 섹션

• 함수가 내부에서 “선언”, “초기화”, “처리” 등 섹션으로 나뉜다면 여러 가지 작업을 하고 있다는 명백한 증거
• 한 가지 일만 하는 함수는 섹션으로 나뉘지 않음

함수 당 하나의 추상화 수준

• 함수 내 모든 문장은 동일한 추상화 수준에 있어야 함
• 추상화 수준의 혼합 예시:
  • 높은 수준: getHtml()
  • 중간 수준: const pagePathName = PathParser.render(pagePath)
  • 낮은 수준: buffer.push("\n")
• 추상화 수준이 섞이면 독자가 세부 구현인지 핵심 개념인지 구분하기 어려워짐
• 세부 내용이 섞이기 시작하면 점점 더 많은 세부 내용이 함수에 추가되는 경향이 생김

하향식 코드 읽기: 내려가기 규칙

• 코드는 위에서 아래로 읽히는 서술 구조처럼 작성되어야 함
• 모든 함수 다음에는 그 다음 수준의 추상화를 가진 함수들이 오도록 구성
• 프로그램이 TO 문단의 집합처럼 읽혀야 함:

TO 페이지를 렌더링하려면, setup과 teardown을 포함하고 HTML로 렌더링한다.
  TO setup을 포함하려면, suite setup과 일반 setup을 포함한다.
    TO suite setup을 포함하려면, 부모 계층에서 "SuiteSetUp" 페이지를 찾아 include 지시어를 추가한다.
      TO 부모 계층을 검색하려면...

• 이 규칙을 따르는 것이 어렵지만, 함수를 짧게 유지하고 “한 가지”만 하도록 만드는 핵심 열쇠

Switch 문

• switch 문은 본질적으로 N가지 일을 함 — 작게 만들기 매우 어려움
• switch 문은 SRP(단일 책임 원칙)와 OCP(개방-폐쇄 원칙)를 위반하기 쉬움

// 나쁜 예: switch가 여기저기에 노출됨
function calculatePay(employee: Employee): Money {
  switch (employee.type) {
    case EmployeeType.COMMISSIONED:
      return calculateCommissionedPay(employee);
    case EmployeeType.HOURLY:
      return calculateHourlyPay(employee);
    case EmployeeType.SALARIED:
      return calculateSalariedPay(employee);
    default:
      throw new InvalidEmployeeTypeError(employee.type);
  }
}
// 이 구조가 isPayday(), deliverPay() 등 여러 곳에 반복됨

// 좋은 예: switch를 Abstract Factory 안에 숨김
interface Employee {
  isPayday(): boolean;
  calculatePay(): Money;
  deliverPay(pay: Money): void;
}

interface EmployeeFactory {
  makeEmployee(record: EmployeeRecord): Employee;
}

class EmployeeFactoryImpl implements EmployeeFactory {
  makeEmployee(record: EmployeeRecord): Employee {
    switch (record.type) {
      case EmployeeType.COMMISSIONED:
        return new CommissionedEmployee(record);
      case EmployeeType.HOURLY:
        return new HourlyEmployee(record);
      case EmployeeType.SALARIED:
        return new SalariedEmployee(record);
      default:
        throw new InvalidEmployeeTypeError(record.type);
    }
  }
}
// 이후 calculatePay, isPayday, deliverPay 등은 Employee 인터페이스를 통해 다형성으로 처리

• switch 허용 원칙: switch 문은 다음 세 조건을 모두 만족할 때만 허용
  1. 딱 한 번만 등장
  2. 다형적 객체를 생성하는 데 사용
  3. 상속 관계 뒤에 숨겨져 시스템의 나머지 부분이 볼 수 없도록 처리

서술적인 이름을 사용하라

• Ward의 원칙: “깨끗한 코드란 각 루틴이 예상한 대로 동작하는 코드다”
• 이 원칙의 절반은 작은 함수에 좋은 이름을 붙이는 것으로 달성됨
• 함수가 작고 집중적일수록, 서술적인 이름을 붙이기 더 쉬움
• 긴 이름을 두려워하지 말 것: 짧고 수수께끼 같은 이름보다 길고 서술적인 이름이 낫고, 긴 주석보다도 나음
• 이름 선택에 시간을 투자할 것: 여러 이름을 시험해보고 그 이름과 함께 코드를 읽어볼 것
  • 좋은 이름을 찾는 과정에서 코드 구조 자체가 개선되는 경우가 많음
• 일관성을 유지할 것: 모듈 내에서 동일한 동사, 명사, 구절을 사용
  • 예: includeSetupAndTeardownPages, includeSetupPages, includeSuiteSetupPage, includeSetupPage
  • 이 이름들이 이야기를 만들어냄

함수 인수

• 이상적인 인수 개수는 0개(무항)
• 다음은 1개(단항), 그 다음은 2개(이항)
• 3개(삼항)는 가능한 한 피할 것
• 3개 초과는 매우 특별한 이유가 없으면 절대 사용하지 않을 것
• 인수가 많을수록 테스트해야 할 조합이 기하급수적으로 증가함
• 출력 인수(output argument)는 입력 인수보다 이해하기 더 어려움 — 독자는 인수가 입력이라고 기대함

단항 함수의 일반적인 형태

단항 함수의 두 가지 일반적인 용도:

1. 인수에 대한 질문: fileExists("MyFile"): boolean
2. 인수를 변환하여 반환: fileOpen("MyFile"): InputStream

덜 일반적이지만 유용한 형태:

3. 이벤트 처리: passwordAttemptFailedNtimes(attempts: number): void
   • 입력 인수는 있지만 출력은 없으며, 시스템의 상태를 변경함
   • 이 형태임이 코드에서 명확하게 드러나야 함

// 나쁜 예: 변환을 출력 인수로 처리
function transform(out: StringBuffer): void { ... }

// 좋은 예: 변환 결과를 반환값으로 처리
function transform(input: StringBuffer): StringBuffer { ... }

플래그 인수

• 불리언 값을 함수에 넘기는 것은 끔찍한 관행
• 함수가 두 가지 이상의 일을 한다고 공개적으로 선언하는 것과 같음

// 나쁜 예
render(true);        // true가 무슨 의미인지 알 수 없음
render(isSuite: boolean);  // 조금 낫지만 여전히 함수가 두 가지 일을 함

// 좋은 예: 두 함수로 분리
renderForSuite(): string { ... }
renderForSingleTest(): string { ... }

이항 함수

• 이항 함수는 단항 함수보다 이해하기 어려움
• 자연스러운 이항이 있는 경우는 허용: new Point(0, 0) — 두 인수가 하나의 값의 정렬된 구성 요소
• 그러나 writeField(outputStream, name)처럼 자연스러운 응집도나 순서가 없는 경우는 문제
• 가능하면 단항으로 변환할 방법을 찾을 것:
  • writeField 메서드를 outputStream의 멤버로 만들어 outputStream.writeField(name) 형태로
  • outputStream을 클래스의 멤버 변수로 만들어 인수에서 제거
  • FieldWriter와 같은 새 클래스를 만들어 생성자에서 outputStream을 받고 write 메서드 제공

삼항 함수

• 삼항 함수는 이항 함수보다 훨씬 이해하기 어려움
• 순서, 멈춤, 무시의 문제가 두 배 이상 증가함
• 삼항 함수를 만들기 전에 매우 신중하게 생각할 것
• 예외적으로 허용 가능한 삼항: assertEquals(1.0, amount, 0.001) — 부동소수점 비교의 상대성을 상기시켜줌

인수 객체

• 인수가 2~3개 이상 필요하다면, 일부 인수를 클래스로 묶는 것을 고려

// 나쁜 예
function makeCircle(x: number, y: number, radius: number): Circle { ... }

// 좋은 예: x, y는 좌표라는 하나의 개념 → 클래스로 묶음
function makeCircle(center: Point, radius: number): Circle { ... }

• 인수를 객체로 묶는 것은 속임수가 아님 — 함께 전달되는 변수들은 이름이 필요한 개념의 일부임

인수 목록

• 가변 인수가 필요할 때: 가변 인수들을 동일하게 취급한다면 List 타입의 단일 인수와 동일

// 이 함수는 실질적으로 이항 함수
function format(formatStr: string, ...args: unknown[]): string { ... }

// 가변 인수 함수도 단항, 이항, 삼항 규칙이 동일하게 적용됨
function monad(...args: number[]): void { ... }
function dyad(name: string, ...args: number[]): void { ... }
function triad(name: string, count: number, ...args: number[]): void { ... }

동사와 키워드

• 단항 함수에서는 함수 이름과 인수가 동사/명사 쌍을 이뤄야 함
  • write(name) — “name”을 “쓴다”
  • writeField(name) — “name”이 “필드”임을 알 수 있어 더 좋음
• 키워드 형식: 인수 이름을 함수 이름에 포함
  • assertEquals → assertExpectedEqualsActual(expected, actual)
  • 인수의 순서를 기억할 필요가 없어짐

부수 효과를 일으키지 마라

• 부수 효과는 거짓말이다 — 함수는 한 가지를 하겠다고 약속하고 숨겨진 다른 일도 함
• 클래스 변수, 전달된 인수, 전역 변수를 몰래 변경하는 행위
• 시간적 결합(temporal coupling) 과 순서 의존성을 초래

// 나쁜 예: checkPassword가 세션을 초기화하는 부수 효과를 가짐
class UserValidator {
  private cryptographer: Cryptographer;

  checkPassword(userName: string, password: string): boolean {
    const user = UserGateway.findByName(userName);
    if (user !== User.NULL) {
      const codedPhrase = user.getPhraseEncodedByPassword();
      const phrase = this.cryptographer.decrypt(codedPhrase, password);
      if (phrase === "Valid Password") {
        Session.initialize(); // 부수 효과! 이름에 드러나지 않음
        return true;
      }
    }
    return false;
  }
}
// checkPassword는 세션이 초기화되어도 안전한 시점에만 호출할 수 있게 됨 → 시간적 결합 발생

• 시간적 결합이 필요하다면 함수 이름에 명시: checkPasswordAndInitializeSession
  • 단, 이 경우 “한 가지만 해라” 원칙에 위반

출력 인수

• 인수는 자연스럽게 입력으로 해석됨
• 출력 인수는 독자에게 혼란을 야기: appendFooter(s) → s가 입력인가, 출력인가?

// 나쁜 예: 출력 인수 사용
function appendFooter(report: StringBuffer): void { ... }

// 좋은 예: 객체의 상태를 변경하는 메서드로 전환
report.appendFooter();

• 일반 원칙: 함수가 무언가의 상태를 변경해야 한다면, 자신이 속한 객체의 상태를 변경할 것

명령과 조회를 분리하라

• 함수는 무언가를 수행하거나 무언가에 답하거나 둘 중 하나만 해야 함
• 객체의 상태를 변경하거나 정보를 반환하거나 — 둘 다 하면 혼란 야기

// 나쁜 예: set이 동사인지 형용사인지 모호함
function set(attribute: string, value: string): boolean { ... }

if (set("username", "unclebob")) { ... }
// "username이 unclebob으로 이전에 설정되어 있으면" 처럼 읽힘

// 좋은 예: 명령과 조회를 명확히 분리
if (attributeExists("username")) {
  setAttribute("username", "unclebob");
  // ...
}

오류 코드보다 예외를 사용하라

• 명령 함수에서 오류 코드를 반환하면 명령과 조회 분리 원칙을 미묘하게 위반
• 오류 코드 반환 시 caller가 즉시 오류를 처리해야 하므로 깊은 중첩 구조 발생

// 나쁜 예: 오류 코드 반환으로 인한 깊은 중첩
if (deletePage(page) === ErrorCode.OK) {
  if (registry.deleteReference(page.name) === ErrorCode.OK) {
    if (configKeys.deleteKey(page.name.makeKey()) === ErrorCode.OK) {
      logger.log("page deleted");
    } else {
      logger.log("configKey not deleted");
    }
  } else {
    logger.log("deleteReference from registry failed");
  }
} else {
  logger.log("delete failed");
  return ErrorCode.ERROR;
}

// 좋은 예: 예외 사용으로 정상 경로와 오류 처리 분리
try {
  deletePage(page);
  registry.deleteReference(page.name);
  configKeys.deleteKey(page.name.makeKey());
} catch (e) {
  logger.log((e as Error).message);
}

Try/Catch 블록 추출하라

• try/catch는 코드 구조를 혼란스럽게 하고 정상 처리와 오류 처리를 섞음
• try/catch 내부를 별도 함수로 추출하는 것이 좋음

// 좋은 예: 오류 처리와 정상 로직을 분리
function deletePage(page: Page): void {
  try {
    deletePageAndAllReferences(page);
  } catch (e) {
    logError(e as Error);
  }
}

function deletePageAndAllReferences(page: Page): void {
  // 실제 삭제 로직만 담당 — 오류 처리 없음
  page.delete();
  registry.deleteReference(page.name);
  configKeys.deleteKey(page.name.makeKey());
}

function logError(e: Error): void {
  logger.log(e.message);
}

오류 처리도 한 가지 작업이다

• 오류 처리도 하나의 작업
• 함수에 try 키워드가 있다면, 그것이 함수의 첫 번째 단어여야 하고 catch/finally 블록 이후에는 아무것도 없어야 함

오류 코드 열거형은 의존성 자석이다

• 오류 코드를 반환하면 오류 코드가 정의된 클래스나 열거형이 필요하게 됨

// 나쁜 예: 오류 열거형을 모든 곳에서 import해야 함
enum ErrorCode {
  OK,
  INVALID,
  NO_SUCH,
  LOCKED,
  OUT_OF_RESOURCES,
  WAITING_FOR_EVENT
}
// 이 열거형이 변경되면 → 이를 사용하는 모든 클래스를 재컴파일·재배포해야 함
// 따라서 프로그래머들은 새 오류 코드를 추가하지 않고 기존 코드를 재사용하려 함

• 예외 클래스를 사용하면: 새 예외는 예외 클래스의 파생 클래스로 추가 → 재컴파일·재배포 없이 확장 가능 (OCP 적용)

반복하지 마라, DRY

• 나쁜 함수 예제에서 동일한 알고리즘이 SetUp, SuiteSetUp, TearDown, SuiteTearDown에 4번 반복됨
• 중복은 코드를 부풀리고, 알고리즘 변경 시 여러 곳을 동시에 수정해야 하며, 누락 오류가 발생하기 쉬움
• 소프트웨어에서 모든 악의 근원은 중복일 수 있음
• 중복을 제거하기 위한 수많은 원칙과 관행들이 존재:
  • 데이터베이스 정규화 (중복 데이터 제거)
  • 객체지향 프로그래밍 (중복 코드를 기반 클래스에 집중)
  • 구조적 프로그래밍, AOP, COP 모두 부분적으로는 중복 제거 전략

구조적 프로그래밍

• Dijkstra의 구조적 프로그래밍 규칙: 모든 함수와 블록은 하나의 입구와 하나의 출구만 가져야 함
  • 함수 내 return은 하나
  • 루프 내 break나 continue 없음
  • goto는 절대 사용하지 않음
• 그러나 함수를 작게 유지한다면, 이 규칙의 이점은 거의 없음
• 함수가 매우 작다면, 경우에 따라 여러 return, break, continue가 표현력을 높이기도 함
• goto는 큰 함수에서만 의미가 있으므로, 작은 함수에서는 아예 사용하지 말 것

이런 함수를 어떻게 작성하는가?

• 소프트웨어 작성은 다른 종류의 글쓰기와 같음
  • 논문이나 기사를 쓸 때: 생각을 먼저 적고, 읽기 좋게 다듬는 과정을 거침
• 처음부터 완벽한 함수를 쓰는 사람은 없다
• 처음에는 길고 복잡하게 작성해도 됨: 들여쓰기가 많고, 중첩 루프도 있고, 인수 목록이 길고, 이름이 임의적이고, 중복도 있음
• 단, 그 어설픈 코드의 모든 줄을 커버하는 단위 테스트는 반드시 작성해야 함
• 그런 다음 코드를 다듬어 나감: 함수 추출, 이름 변경, 중복 제거, 메서드 정렬, 클래스 분리 — 항상 테스트를 통과시키면서
• 결국 이 챕터의 규칙을 따르는 함수들이 완성됨

정리

• 모든 시스템은 해당 시스템을 기술하기 위해 프로그래머가 설계한 도메인 특화 언어(DSL) 로 구성됨
• 함수는 그 언어의 동사, 클래스는 명사
• 마스터 프로그래머는 시스템을 “작성할 프로그램”이 아닌 “말할 이야기” 로 생각함
• 프로그래밍의 예술은 곧 언어 설계의 예술

이 챕터는 함수를 잘 작성하는 기법에 관한 것이다. 그러나 진짜 목표는 시스템의 이야기를 전달하는 것이며, 작성하는 함수들이 명확하고 정밀한 언어로 깔끔하게 조화를 이뤄야 한다는 것을 잊지 말 것.

핵심 요약

• 함수는 작게: 2~4줄이 이상적. 절대로 20줄을 넘기지 말 것
• 한 가지만: 함수 이름의 한 단계 아래 추상화 작업만 수행
• 추상화 수준 통일: 함수 내 모든 문장은 동일한 추상화 수준이어야 함
• 내려가기 규칙: 코드는 위에서 아래로 읽히는 서술 구조
• Switch는 숨겨라: Abstract Factory 뒤에 단 한 번만, 다형성으로 처리
• 서술적 이름: 길더라도 서술적인 이름이 짧고 모호한 이름보다 낫다
• 인수는 적게: 0개가 이상적, 3개 이상은 피할 것
• 부수 효과 없음: 함수는 약속한 한 가지만 하고 숨겨진 일을 하면 안 됨
• 명령/조회 분리: 상태 변경과 정보 반환을 동시에 하지 말 것
• 예외 사용: 오류 코드 대신 예외 사용, try/catch 내부는 별도 함수로 추출
• DRY: 중복은 소프트웨어의 모든 악의 근원일 수 있다
• 구조적 프로그래밍: 함수가 충분히 작으면 단일 출구 규칙은 선택 사항

4장. 주석

“나쁜 코드에 주석을 달지 마라 — 새로 짜라.” — Brian W. Kernighan & P. J. Plaugher

• 잘 작성된 주석은 도움이 되지만, 쓸모없는 주석은 모듈을 어지럽히고, 낡고 부정확한 주석은 심각한 해악을 끼침
• 주석은 “순수한 선”이 아니다 — 기껏해야 필요악
• 프로그래밍 언어가 충분히 표현력이 있거나, 개발자가 언어를 능숙하게 다룰 수 있다면 주석은 거의 필요하지 않음
• 주석의 올바른 용도: 코드로 의도를 표현하지 못한 실패를 보완하는 것
  • 주석을 써야 하는 상황에 처했다면, 코드로 표현할 방법이 없는지 먼저 고민할 것
  • 코드로 표현에 성공하면 스스로를 칭찬할 것, 주석을 쓰면 자신의 표현 실패를 자각할 것

주석이 거짓말을 하는 이유

• 코드는 변하고 진화하지만, 주석은 항상 따라오지 못한다
• 코드 덩어리가 이리저리 이동해도 주석은 제자리에 남아 고아가 됨
• 시간이 지날수록 주석은 코드와 멀어지고, 점점 부정확해짐
• 부정확한 주석은 아예 없는 것보다 훨씬 나쁘다 — 잘못된 기대를 심어주고, 따르지 말아야 할 규칙을 강요함
• 진실은 오직 한 곳, 코드 안에만 있다

주석은 나쁜 코드를 대체하지 못한다

• 주석을 쓰는 가장 흔한 동기: 코드가 엉망임을 스스로 알기 때문
• "이 코드는 복잡하니까 주석을 달아야지!" 가 아니라 "코드를 정리해야지!"
• 주석이 적고 명확한 코드 > 주석이 많고 복잡한 코드
• 엉망을 설명하는 주석을 쓰는 시간에 그 엉망을 정리하라

코드로 의도를 표현하라

• 코드는 설명하기 어려운 수단이라는 인식이 있지만, 이는 잘못된 통념
• 대부분의 의도는 몇 초의 고민만으로 코드 자체에 담을 수 있음

나쁜 예시 — 주석에 의존:

// 직원이 전체 혜택을 받을 자격이 있는지 확인
if ((employee.flags & HOURLY_FLAG) && employee.age > 65) { ... }

좋은 예시 — 코드로 표현:

if (employee.isEligibleForFullBenefits()) { ... }

• 주석으로 쓰고 싶은 내용을 함수 이름으로 만들어버리는 것이 핵심

좋은 주석

가장 좋은 주석은 쓰지 않아도 되는 방법을 찾아낸 주석이다.

법적 주석

• 기업 코딩 표준에 따라 법적 이유로 작성해야 하는 주석 (저작권, 라이선스 등)
• 소스 파일 맨 앞에 넣는 것이 일반적이며, IDE에서 자동으로 접어 보여주므로 방해가 덜함

// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// Released under the terms of the GNU General Public License version 2 or later.

• 주석 안에 모든 약관을 넣지 말고, 표준 라이선스나 외부 문서를 참조할 것

정보를 제공하는 주석

• 코드의 기본적인 정보를 제공할 때 유용할 수 있음
• 단, 가능하면 함수 이름 자체에 정보를 담는 것이 더 좋음

// kk:mm:ss EEE, MMM dd, yyyy 형식과 일치
const timeMatcher = /\d*:\d*:\d* \w*, \w* \d*, \d*/;

• 위 예시처럼 정규식의 패턴 의도를 설명할 때는 유용하지만, 이 역시 날짜/시간 변환을 담당하는 별도 클래스로 분리하면 주석 자체가 불필요해질 수 있음

의도를 설명하는 주석

• 구현 정보를 넘어 설계 결정의 의도를 담는 주석
• 독자가 동의하지 않더라도, 작성자가 무엇을 하려 했는지 이해할 수 있게 함

// 경쟁 조건(race condition)을 유발하기 위한 최선의 시도로,
// 다수의 스레드를 생성한다.
for (let i = 0; i < 25000; i++) {
  const thread = new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
  thread.start();
}

명료화 주석

• 모호한 인수나 반환값의 의미를 읽기 쉽게 번역해주는 주석
• 표준 라이브러리나 수정 불가능한 코드를 다룰 때 특히 유용
• 단, 명료화 주석이 틀릴 위험도 있으므로 신중히 작성하고 정확성을 철저히 검증할 것

assertTrue(a.compareTo(a) === 0); // a == a
assertTrue(a.compareTo(b) !== 0); // a != b
assertTrue(a.compareTo(b) === -1); // a < b
assertTrue(b.compareTo(a) === 1);  // b > a

결과를 경고하는 주석

• 다른 개발자에게 특정 결과를 경고하는 주석
• 불필요한 실수를 방지하는 데 효과적

// 실행하는 데 시간이 매우 오래 걸리므로 여유가 있을 때만 실행하세요.
function testWithReallyBigFile() { ... }

// SimpleDateFormat은 스레드 안전하지 않으므로
// 인스턴스를 매번 독립적으로 생성해야 한다.
function makeStandardHttpDateFormat(): SimpleDateFormat {
  return new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
}

TODO 주석

• 지금 당장 할 수 없지만 나중에 해야 할 작업을 // TODO 형식으로 남기는 것
• 쓸 수 있는 상황: 더 이상 필요 없는 기능 삭제 알림, 더 나은 이름 요청, 계획된 이벤트에 따른 변경 알림 등
• TODO는 나쁜 코드를 남겨두는 핑계가 되어선 안 된다
• 대부분의 IDE는 TODO를 추적하는 기능을 제공하므로 분실될 위험은 낮음
• 코드에 TODO가 너무 많이 쌓이지 않도록 주기적으로 검토하고 제거할 것

// TODO: checkout 모델을 구현하면 이 함수는 제거될 예정
protected makeVersion(): VersionInfo | null {
  return null;
}

중요성 강조 주석

• 겉보기에 사소해 보이지만 실은 매우 중요한 코드를 강조할 때 사용

const listItemContent = match[3].trim();
// trim은 매우 중요하다. 시작 공백을 제거하지 않으면
// 이 항목이 다른 목록으로 인식될 수 있다.
new ListItemWidget(this, listItemContent, this.level + 1);

공개 API의 문서화 주석

• 공개 API를 작성할 때는 좋은 문서 주석(JSDoc 등)이 필수적
• TypeScript 기준으로는 JSDoc 형태의 주석이 이에 해당
• 단, 이 챕터의 나머지 조언들을 함께 적용해야 함 — 문서 주석도 오해를 유발하거나 부정확해질 수 있음

나쁜 주석

대부분의 주석이 이 범주에 속한다. 나쁜 코드에 대한 지팡이, 불충분한 결정의 변명, 혼자 중얼거리는 독백에 불과하다.

독백 주석

• 의무감에 혹은 프로세스 요구에 의해 억지로 다는 주석
• 주석의 의미가 불분명하여 다른 모듈을 뒤져야만 이해할 수 있는 주석은 실패한 주석

loadProperties() {
  try {
    // ...파일 로드
  } catch (e) {
    // 프로퍼티 파일이 없으면 모든 기본값이 로드된다
    // (누가 기본값을 로드하는가? 언제? 이 catch가 처리하는가?)
  }
}

• 위 주석은 작성자에게만 의미가 있고, 독자는 의미를 파악하기 위해 코드를 더 뒤져야 함

중복 주석

• 코드 자체보다 읽는 데 더 오래 걸리면서 아무 정보도 추가하지 않는 주석
• 코드를 정당화하지도, 의도나 근거를 제공하지도 않음
• 코드보다 덜 정확하며, 독자가 주석의 부정확함을 진실로 받아들이도록 유도함

// this.closed가 true가 되면 반환하는 유틸리티 메서드.
// 타임아웃에 도달하면 예외를 던진다.
waitForClose(timeoutMillis: number): void {
  if (!this.closed) {
    this.wait(timeoutMillis);
    if (!this.closed)
      throw new Error("MockResponseSender could not be closed");
  }
}

• Tomcat의 ContainerBase.java 같은 예시처럼, 클래스 필드에 자명한 내용을 JSDoc으로 일일이 달아놓은 코드는 코드를 가리고 혼란을 줄 뿐

오해를 불러일으키는 주석

• 의도는 좋았지만 충분히 정확하지 않아 오해를 일으키는 주석
• 위 waitForClose 예시에서 주석은 this.closed가 true가 되면 반환한다고 했지만, 실제로는 this.closed가 이미 true인 경우에만 즉시 반환하고, 그렇지 않으면 타임아웃 후 예외를 던짐
• 이 미묘한 차이 때문에 다른 개발자가 this.closed가 true로 바뀌는 순간 반환될 것이라 믿고 호출했다가 디버깅 지옥에 빠질 수 있음

의무적으로 다는 주석

• 모든 함수에 JSDoc을 달아야 한다, 모든 변수에 주석을 달아야 한다는 규칙은 어리석음
• 이런 주석은 코드를 어지럽히고, 거짓말을 퍼뜨리며, 혼란과 무질서를 초래함

/**
 * @param title CD의 제목
 * @param author CD의 저자
 * @param tracks CD의 트랙 수
 * @param durationInMinutes CD의 재생 시간(분)
 */
addCD(title: string, author: string, tracks: number, durationInMinutes: number): void {
  // ...
}

• 파라미터명과 완전히 동일한 내용만 반복하는 JSDoc은 코드를 난독화할 뿐

이력을 기록하는 주석

• 모듈 상단에 변경할 때마다 로그를 추가하는 관행
• 소스 코드 관리 시스템(Git 등)이 존재하는 현재는 완전히 불필요
• 이런 주석은 제거해야 함

// * Changes (from 11-Oct-2001)
// * --------------------------
// * 11-Oct-2001 : Re-organised the class and moved it to new package (DG);
// * 05-Nov-2001 : Added a getDescription() method (DG);
// * ...수십 줄 계속...

있으나 마나 한 주석

• 명백한 사실만 반복하며 새로운 정보를 전혀 제공하지 않는 주석
• 읽다 보면 무시하는 습관이 생기고, 결국 중요한 주석도 함께 무시하게 됨

/** 기본 생성자. */
constructor() {}

/** 월(月). */
private dayOfMonth: number;

/**
 * 월(月)을 반환한다.
 * @return 월(月)
 */
getDayOfMonth(): number {
  return this.dayOfMonth;
}

끔찍한 주석

• JSDoc도 소음이 될 수 있음 — 문서를 제공하겠다는 잘못된 욕심에서 나온 중복 주석
• 복붙 실수까지 발생하여 더욱 신뢰를 잃게 됨

/** The name. */
private name: string;
/** The version. */
private version: string;
/** The licenceName. */
private licenceName: string;
/** The version. */  // ← 복붙 오류! info인데 version이라고 되어 있음
private info: string;

• 작성자도 주의를 기울이지 않은 주석을 독자가 신뢰할 이유가 없음

함수나 변수로 표현할 수 있으면 주석을 쓰지 마라

나쁜 예시:

// 전역 목록 <mod>의 모듈이 우리가 속한 서브시스템에 의존하는가?
if (smodule.getDependSubsystems().includes(subSysMod.getSubSystem())) { ... }

좋은 예시 — 변수로 표현:

const moduleDependees = smodule.getDependSubsystems();
const ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.includes(ourSubSystem)) { ... }

위치 표시 주석

• 소스 파일의 특정 위치를 표시하기 위한 주석

// Actions //////////////////////////////////

• 극히 드물게 관련 함수들을 모아놓을 때 의미가 있지만, 대부분은 제거해야 할 잡음
• 너무 자주 사용하면 배경 소음이 되어 무시당함
• 꼭 필요한 경우에만, 효과가 분명할 때만 사용할 것

닫는 중괄호에 다는 주석

• 중첩이 깊고 긴 함수에서 닫는 중괄호에 주석을 다는 관행

} // while
} // try
} // if
} // main

• 짧고 캡슐화된 함수에서는 불필요한 잡음
• 닫는 중괄호에 주석을 달고 싶다면, 함수를 짧게 만드는 것이 올바른 해결책

저자 표시 주석

/* Added by Rick */

• 소스 코드 관리 시스템이 누가 언제 무엇을 추가했는지 훨씬 잘 기억함
• 이런 주석은 수년간 방치되며 점점 부정확하고 무의미해짐
• 저자 정보는 Git blame 등 소스 관리 시스템에 맡길 것

주석으로 처리한 코드

• 이것만큼 해로운 관행도 드물다. 절대 하지 마라.

const response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// const resultsStream = formatter.getResultStream();
// const reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

• 주석 처리된 코드를 본 다른 개발자는 삭제할 용기를 내지 못함 — 이유가 있겠지, 중요한 거겠지 생각하기 때문
• 결국 주석 처리된 코드는 나쁜 와인 찌꺼기처럼 바닥에 쌓임
• 소스 코드 관리 시스템이 코드를 기억해준다. 그냥 지워라. 절대 잃어버리지 않는다.

HTML 주석

• 소스 코드 주석에 HTML을 넣는 것은 혐오스러운 관행
• 주석을 가장 쉽게 읽어야 할 곳(에디터/IDE)에서 오히려 읽기 어렵게 만듦
• Javadoc/JSDoc 도구가 HTML로 출력해야 한다면, HTML을 삽입하는 것은 도구의 책임이지 개발자의 책임이 아님

비지역적 정보

• 주석은 근처의 코드를 설명해야 함. 시스템 전체에 대한 정보를 지역 주석에 넣으면 안 됨

/**
 * fitnesse가 실행될 포트. 기본값은 8082.
 * @param fitnessePort
 */
setFitnessePort(fitnessePort: number): void {
  this.fitnessePort = fitnessePort;
}

• 이 함수는 기본값을 전혀 제어하지 않음. 기본값이 변경되어도 이 주석이 업데이트될 보장이 없음

너무 많은 정보

• 역사적인 토론이나 관련 없는 세부 구현 설명을 주석에 쏟아붓지 마라
• RFC 번호 외에 base64 인코딩 알고리즘의 24비트 그룹 처리 방식까지 주석에 넣는 것은 과잉

불분명한 관계

• 주석과 그것이 설명하는 코드 사이의 관계는 명백해야 한다

/*
 * 모든 픽셀(+ 필터 바이트)을 담을 수 있을 만큼 크고,
 * 헤더 정보를 위해 200바이트를 추가한 배열로 시작
 */
this.pngBytes = new Uint8Array(((this.width + 1) * this.height * 3) + 200);

• 필터 바이트가 무엇인가? +1과 관련 있는가? *3과 관련 있는가? 픽셀이 1바이트인가? 200은 왜인가?
• 주석이 그 자체로 또 다른 설명을 필요로 한다면 실패한 주석

함수 헤더

• 짧은 함수에는 헤더 주석이 필요 없음
• 한 가지 일을 하는 작은 함수에 잘 선택된 이름을 붙이는 것이 주석 헤더보다 훨씬 낫다

비공개 코드의 문서 주석

• 공개 API에는 JSDoc이 유용하지만, 외부에 공개되지 않는 내부 코드에는 불필요
• 내부 클래스와 함수를 위한 JSDoc 페이지를 생성하는 것은 일반적으로 유용하지 않음
• JSDoc의 형식적인 틀이 오히려 코드를 어지럽히고 집중을 방해함

핵심 요약

• 법적 주석: 좋은 주석 / 저작권·라이선스는 필요하지만 약관 전문을 넣지 말 것
• 정보 제공 주석: 좋은 주석 / 유용할 수 있으나 함수 이름으로 대체 가능한지 먼저 고려
• 의도 설명 주석: 좋은 주석 / 설계 결정의 이유를 담아 독자의 이해를 도움
• 명료화 주석: 좋은 주석 / 수정 불가한 코드의 모호함을 해소하되 정확성 검증 필수
• 경고 주석: 좋은 주석 / 다른 개발자의 실수를 사전에 방지
• TODO 주석: 좋은 주석 / 나쁜 코드의 핑계가 되선 안 되며 주기적으로 제거할 것
• 중요성 강조 주석: 좋은 주석 / 사소해 보이지만 중요한 코드에 주의를 환기
• 독백 주석: 나쁜 주석 / 작성자만 이해하고 독자는 다른 코드를 뒤져야 함
• 중복 주석: 나쁜 주석 / 코드보다 덜 정확하고 더 읽기 어려운 설명
• 오해 주석: 나쁜 주석 / 미묘하게 부정확한 주석이 디버깅 지옥을 만듦
• 의무적 주석: 나쁜 주석 / 모든 함수/변수에 주석을 달아야 한다는 규칙은 어리석음
• 이력 주석: 나쁜 주석 / Git이 있는 지금, 완전히 불필요
• 있으나 마나한 주석: 나쁜 주석 / 자명한 내용의 반복, 무시하는 습관을 기름
• 위치 표시 주석: 나쁜 주석 / 극히 드물게만 사용, 남용하면 배경 소음
• 닫는 괄호 주석: 나쁜 주석 / 함수가 짧으면 불필요, 짧게 만드는 것이 해결책
• 저자 표시 주석: 나쁜 주석 / Git blame이 더 정확하게 기억함
• 주석 처리된 코드: 나쁜 주석 / 절대 하지 마라. Git이 기억한다. 그냥 지워라
• HTML 주석: 나쁜 주석 / HTML 변환은 도구의 몫, 개발자가 할 일이 아님
• 비지역적 정보: 나쁜 주석 / 주석은 근처의 코드만 설명해야 함
• 과도한 정보: 나쁜 주석 / 역사적 토론·관련 없는 세부 내용 금지
• 불분명한 관계: 나쁜 주석 / 주석 자체가 설명이 필요하면 실패한 주석
• 비공개 코드의 JSDoc: 나쁜 주석 / 내부 코드에 공식 문서 주석은 불필요한 형식주의

핵심 원칙: 주석을 쓰고 싶을 때마다 그 의도를 코드로 표현할 방법을 먼저 찾아라. 코드로 표현에 성공하는 것이 진짜 실력이며, 주석은 그 실패의 흔적이다.

5장. 형식 맞추기

코드를 들여다볼 때, 사람들이 단정함, 일관성, 세부사항에 대한 주의를 보고 감탄하길 원한다. 질서 정연함에 감동받길 원한다. 만약 그들이 술 취한 선원 무리가 짠 것 같은 뒤엉킨 코드를 본다면, 프로젝트의 다른 모든 측면에도 같은 무신경함이 만연해 있다고 결론지을 것이다.

• 코드는 반드시 깔끔하게 포맷되어야 함
• 포맷을 지배하는 간단한 규칙을 선택하고, 그 규칙을 일관되게 적용해야 함
• 팀에서 작업한다면 팀 전체가 동의한 단일 포맷 규칙에 모든 멤버가 따라야 함
• 포맷 규칙을 자동으로 적용해주는 도구(ESLint + Prettier 등)를 활용하면 도움이 됨

포맷의 목적

• 코드 포맷은 커뮤니케이션이며, 커뮤니케이션은 전문 개발자의 제1 원칙
• “일단 돌아가게 만드는 것”이 첫 번째가 아님
• 오늘 작성한 기능은 다음 릴리즈에서 바뀔 수 있지만, 코드의 가독성은 이후 모든 변경에 깊은 영향을 미침
• 코딩 스타일과 가독성은 원래 코드가 형태를 알아볼 수 없을 만큼 바뀐 뒤에도 유지보수성과 확장성에 계속 영향을 줌
• 스타일과 규율은 살아남는다, 코드 자체가 살아남지 않더라도

수직 포맷

파일 크기

• 소스 파일은 얼마나 커야 하는가?
• FitNesse(약 50,000줄 규모의 시스템)는 평균 65줄, 대부분 200줄 이하, 최대 500줄 이하의 파일로 구성됨
• 작은 파일은 큰 파일보다 이해하기 쉽다는 원칙
• 200줄 정도, 최대 500줄을 넘지 않는 것이 바람직함 (절대 규칙은 아니지만 강하게 권장)

신문 기사 은유

• 잘 쓰인 신문 기사처럼 소스 파일을 구성할 것
  • 상단: 헤드라인 - 파일명만으로 올바른 모듈인지 판단 가능해야 함
  • 첫 부분: 고수준 개념과 알고리즘 제공
  • 아래로 내려갈수록: 세부사항 증가, 최저수준 함수와 디테일로 마무리
• 신문은 수많은 짧은 기사들로 구성됨 - 하나의 긴 이야기 덩어리가 아님
• 파일도 마찬가지: 한 가지 개념, 위에서 아래로 자연스럽게 읽히는 구조

개념 사이의 수직적 여백

• 코드는 왼쪽에서 오른쪽, 위에서 아래로 읽힘
• 각 줄은 표현식 또는 절을 나타내고, 각 줄 그룹은 완결된 하나의 생각을 표현
• 생각들은 빈 줄로 분리되어야 함

// 좋은 예: 패키지 선언, import, 각 함수 사이에 빈 줄 존재
import { Pattern } from './pattern';
import { ParentWidget } from './parentWidget';

export class BoldWidget extends ParentWidget {
  static readonly REGEXP = "'''.+?'''";
  private pattern: Pattern;

  constructor(parent: ParentWidget, text: string) {
    super(parent);
    const match = this.pattern.exec(text);
    this.addChildWidgets(match![1]);
  }

  render(): string {
    return `<b>${this.childHtml()}</b>`;
  }
}

// 나쁜 예: 빈 줄이 없으면 코드 덩어리가 뭉개져 읽기 어려움
import { Pattern } from './pattern';
import { ParentWidget } from './parentWidget';
export class BoldWidget extends ParentWidget {
  static readonly REGEXP = "'''.+?'''";
  private pattern: Pattern;
  constructor(parent: ParentWidget, text: string) {
    super(parent);
    const match = this.pattern.exec(text);
    this.addChildWidgets(match![1]);
  }
  render(): string {
    return `<b>${this.childHtml()}</b>`;
  }
}

• 눈의 초점을 흐리게 하면 차이가 극명하게 드러남 - 빈 줄이 있는 코드는 그룹이 튀어나오고, 없는 코드는 흐릿한 덩어리로 보임

수직 밀도

• 개방성이 개념을 분리한다면, 수직 밀도는 밀접한 연관을 의미
• 서로 긴밀하게 관련된 코드 줄들은 수직으로 촘촘하게 배치해야 함

// 나쁜 예: 불필요한 주석이 두 인스턴스 변수의 밀접한 연관을 끊어버림
class ReporterConfig {
  /**
   * 리포터 리스너의 클래스 이름
   */
  private className: string;

  /**
   * 리포터 리스너의 프로퍼티
   */
  private properties: Property[] = [];

  addProperty(property: Property): void {
    this.properties.push(property);
  }
}

// 좋은 예: 관련 변수들이 밀집되어 한눈에 파악 가능
class ReporterConfig {
  private className: string;
  private properties: Property[] = [];

  addProperty(property: Property): void {
    this.properties.push(property);
  }
}

수직 거리

• 밀접하게 관련된 개념들은 서로 수직으로 가까이 두어야 함 [G10]
• 독자가 소스 파일 여기저기를 뛰어다니게 만들면 안 됨
• 이 규칙은 별도 파일에 속하는 개념에는 적용 불가 - 밀접한 개념이라면 정당한 이유 없이 다른 파일로 분리하지 말 것

변수 선언(Variable Declarations)

• 변수는 사용하는 곳과 최대한 가까이 선언
• 함수가 짧다면, 로컬 변수는 각 함수의 상단에 선언

function readPreferences(): void {
  let stream: NodeJS.ReadableStream | null = null;
  try {
    stream = fs.createReadStream(getPreferencesFile());
    setPreferences(new Properties(getPreferences()));
    getPreferences().load(stream);
  } catch (e) {
    if (stream !== null) {
      try { stream.destroy(); } catch {}
    }
  }
}

• 루프 제어 변수는 루프 구문 내에 선언

function countTestCases(): number {
  let count = 0;
  for (const test of tests) {
    count += test.countTestCases();
  }
  return count;
}

• 인스턴스 변수는 클래스 최상단에 선언
  • 잘 설계된 클래스에서는 대부분의 메서드가 인스턴스 변수를 사용하므로 수직 거리가 증가하지 않음
  • “어디서 인스턴스 변수를 찾을 수 있는가”를 누구나 알 수 있어야 함
  • 클래스 중간에 숨겨진 인스턴스 변수는 독자가 우연히 발견해야만 하는 함정

종속 함수(Dependent Functions)

• 한 함수가 다른 함수를 호출한다면 두 함수는 수직으로 가까이 있어야 함
• 호출하는 함수(caller)가 호출되는 함수(callee) 위에 위치해야 함
• 이 규칙을 일관되게 따르면, 독자는 함수 정의가 사용 직후에 나올 것임을 신뢰하게 됨

// 좋은 예: makeResponse -> getPageNameOrDefault -> loadPage 순으로 자연스러운 흐름
class WikiPageResponder {
  makeResponse(context: FitNesseContext, request: Request): Response {
    const pageName = this.getPageNameOrDefault(request, 'FrontPage');
    this.loadPage(pageName, context);
    if (!this.page) return this.notFoundResponse(context, request);
    return this.makePageResponse(context);
  }

  private getPageNameOrDefault(request: Request, defaultPageName: string): string {
    const pageName = request.getResource();
    return pageName.trim() === '' ? defaultPageName : pageName;
  }

  private loadPage(resource: string, context: FitNesseContext): void {
    // ...
  }
  // ...
}

인사이트: 'FrontPage'와 같은 상수는 실제로 사용하는 저수준 함수 안에 묻히는 것보다, 의미가 통하는 수준(호출하는 쪽)에서 전달되는 것이 더 적절하다 [G35].

개념적 유사성(Conceptual Affinity)

• 서로 끌어당기는 힘이 있는 코드는 가까이 있어야 함
• 직접 호출 관계 외에도, 비슷한 동작을 수행하는 함수 그룹은 유사성을 가짐

// 공통 명명 규칙을 공유하고 같은 기본 작업의 변형을 수행하는 함수들 - 호출 관계 없어도 함께 있어야 함
class Assert {
  static assertTrue(condition: boolean, message?: string): void {
    if (!condition) this.fail(message ?? '');
  }

  static assertFalse(condition: boolean, message?: string): void {
    this.assertTrue(!condition, message);
  }
  // ...
}

수직 순서

• 함수 호출 의존성은 아래 방향을 가리켜야 함 - 호출되는 함수는 호출하는 함수 아래에
• 소스 코드 모듈이 고수준에서 저수준으로 흐르는 자연스러운 흐름 생성
• 신문 기사처럼 가장 중요한 개념이 먼저, 저수준 세부사항은 마지막에
• 파일을 훑을 때 처음 몇 개의 함수만 봐도 전체 맥락을 파악할 수 있음

수평 포맷

줄 길이

• 분석 결과, 프로그래머들은 짧은 줄을 선호함
• 20~60자 범위의 줄이 전체의 약 40%를 차지
• 과거의 80자 제한은 다소 임의적이나, 100~120자 정도가 적절
• 120자를 넘는 것은 부주의한 것

수평 여백과 밀도

• 수평 공백은 강하게 연관된 것을 연결하고, 약하게 연관된 것을 분리하는 데 사용

// 할당 연산자 양쪽에 공백 -> 좌변과 우변이라는 두 주요 요소를 명확히 분리
private measureLine(line: string): void {
  this.lineCount++;
  const lineSize = line.length;
  this.totalChars += lineSize;
  this.lineWidthHistogram.addLine(lineSize, this.lineCount);
  this.recordWidestLine(lineSize);
}

• 함수명과 여는 괄호 사이에는 공백을 두지 않음 - 함수와 인수는 밀접하게 연관되어 있기 때문
• 인수 사이의 쉼표 뒤에는 공백 - 인수들이 별개임을 강조

// 연산자 우선순위를 공백으로 표현
class Quadratic {
  static root1(a: number, b: number, c: number): number {
    const det = this.determinant(a, b, c);
    return (-b + Math.sqrt(det)) / (2*a); // 곱셈은 공백 없음(고우선순위), 덧셈/나눗셈은 공백(저우선순위)
  }

  private static determinant(a: number, b: number, c: number): number {
    return b*b - 4*a*c;
  }
}

주의: 대부분의 코드 포맷터는 연산자 우선순위를 고려하지 않고 일괄 공백을 적용하므로, 위와 같은 섬세한 간격은 자동 포맷 후 사라지는 경향이 있음

수평 정렬

• 변수 선언이나 대입문을 세로로 정렬하는 것은 유용하지 않음

// 나쁜 예: 수평 정렬은 잘못된 것을 강조하게 만듦 - 타입보다 변수명 목록에 눈이 가고, 연산자보다 우변 값에 눈이 가게 됨
class FitNesseExpediter {
  private socket              : Socket;
  private input               : Readable;
  private output              : Writable;
  private request             : Request;
  private response            : Response;
  private requestParsingLimit : number;
}

// 좋은 예: 정렬하지 않으면 오히려 중요한 결함이 보임 - 선언 목록이 길다면 클래스를 분리해야 한다는 신호
class FitNesseExpediter {
  private socket: Socket;
  private input: Readable;
  private output: Writable;
  private request: Request;
  private response: Response;
  private requestParsingLimit: number;
}

• 선언 목록이 너무 길다면 → 문제는 정렬의 부재가 아니라 목록의 길이 자체, 즉 클래스 분리 신호

들여쓰기

• 소스 파일은 계층적 윤곽 구조
  • 파일 전체에 해당하는 정보
  • 파일 내 개별 클래스에 해당하는 정보
  • 클래스 내 메서드에 해당하는 정보
  • 메서드 내 블록에 해당하는 정보
  • 블록 안의 블록 (재귀적으로)
• 각 계층의 범위를 시각적으로 드러내기 위해 들여쓰기 사용
• 프로그래머는 들여쓰기에 매우 의존함 - 들여쓰기 없는 코드는 인간이 사실상 읽을 수 없음

// 나쁜 예: 들여쓰기 없음 - 구조 파악이 거의 불가능
class FitNesseServer { private context: FitNesseContext; constructor(context: FitNesseContext) { this.context = context; } serve(s: Socket): void { this.serveWithTimeout(s, 10000); } serveWithTimeout(s: Socket, timeout: number): void { try { const sender = new FitNesseExpediter(s, this.context); sender.setRequestParsingTimeLimit(timeout); sender.start(); } catch(e) { console.error(e); } } }

// 좋은 예: 들여쓰기로 구조가 한눈에 보임
class FitNesseServer {
  private context: FitNesseContext;

  constructor(context: FitNesseContext) {
    this.context = context;
  }

  serve(s: Socket): void {
    this.serveWithTimeout(s, 10000);
  }

  serveWithTimeout(s: Socket, timeout: number): void {
    try {
      const sender = new FitNesseExpediter(s, this.context);
      sender.setRequestParsingTimeLimit(timeout);
      sender.start();
    } catch (e) {
      console.error(e);
    }
  }
}

들여쓰기 규칙 파괴(Breaking Indentation)

• 짧은 if, 짧은 while, 짧은 함수라도 들여쓰기 규칙을 무너뜨리려는 유혹을 피할 것

// 나쁜 예: 스코프를 한 줄로 축소
class CommentWidget extends TextWidget {
  static readonly REGEXP = '^#[^\r\n]*(?:(?:\r\n)|\n|\r)?';
  constructor(parent: ParentWidget, text: string) { super(parent, text); }
  render(): string { return ''; }
}

// 좋은 예: 스코프를 명확히 전개하고 들여쓰기 적용
class CommentWidget extends TextWidget {
  static readonly REGEXP = '^#[^\r\n]*(?:(?:\r\n)|\n|\r)?';

  constructor(parent: ParentWidget, text: string) {
    super(parent, text);
  }

  render(): string {
    return '';
  }
}

더미 스코프

• while이나 for의 바디가 더미(빈 것)인 구조는 가능하면 피할 것
• 피할 수 없다면, 더미 바디를 적절히 들여쓰고 중괄호로 감싸야 함
• 세미콜론이 while 루프와 같은 줄에 조용히 앉아 있으면 눈에 잘 띄지 않아 버그 유발

// 나쁜 예: 세미콜론이 같은 줄에 숨어있음
while (buffer.read(buf, 0, readBufferSize) !== -1);

// 좋은 예: 더미 바디가 명확히 보임
while (buffer.read(buf, 0, readBufferSize) !== -1) {
  // intentionally empty
}

팀 규칙

• 제목 자체가 말장난: 모든 프로그래머는 자신만의 포맷 규칙을 갖고 있지만, 팀에서 일한다면 팀의 규칙을 따른다
• 개발자 팀은 단일 포맷 스타일에 합의하고, 모든 구성원이 그 스타일을 따라야 함
• 소프트웨어는 일관된 스타일을 가져야 함 - 여러 개인의 의견 충돌로 쓰인 것처럼 보이면 안 됨
• FitNesse 프로젝트 예시: 팀이 10분 만에 중괄호 위치, 들여쓰기 크기, 클래스·변수·메서드 명명 방식에 합의 → IDE 포맷터에 인코딩하여 일관되게 유지
• 이 규칙들이 내가 선호하는 규칙이 아니었다 - 팀이 결정한 규칙이었고, 팀의 일원으로서 따랐음

좋은 소프트웨어 시스템은 읽기 좋은 문서들의 집합이다. 하나의 소스 파일에서 본 포맷 신호가 다른 파일에서도 동일한 의미를 가짐을 독자가 신뢰할 수 있어야 한다. 소스 코드에 다양한 개인 스타일의 혼재라는 복잡성을 더하는 것은 최악이다.

Uncle Bob의 포맷팅 규칙

• 포맷 규칙은 단순하게 유지
• 코드 자체가 최고의 코딩 표준 문서라는 철학
• Listing 5-6 (CodeAnalyzer.java)을 TypeScript로 재구성한 예:

import * as fs from 'fs';
import * as readline from 'readline';

class LineWidthHistogram {
  private lines: Map<number, number[]> = new Map();

  addLine(lineSize: number, lineCount: number): void {
    if (!this.lines.has(lineSize)) this.lines.set(lineSize, []);
    this.lines.get(lineSize)!.push(lineCount);
  }

  getLinesForWidth(width: number): number[] {
    return this.lines.get(width) ?? [];
  }

  getWidths(): Set<number> {
    return new Set(this.lines.keys());
  }
}

export class CodeAnalyzer {
  private lineCount = 0;
  private maxLineWidth = 0;
  private widestLineNumber = 0;
  private lineWidthHistogram = new LineWidthHistogram();
  private totalChars = 0;

  async analyzeFile(filePath: string): Promise<void> {
    const rl = readline.createInterface({ input: fs.createReadStream(filePath) });
    for await (const line of rl) {
      this.measureLine(line);
    }
  }

  private measureLine(line: string): void {
    this.lineCount++;
    const lineSize = line.length;
    this.totalChars += lineSize;
    this.lineWidthHistogram.addLine(lineSize, this.lineCount);
    this.recordWidestLine(lineSize);
  }

  private recordWidestLine(lineSize: number): void {
    if (lineSize > this.maxLineWidth) {
      this.maxLineWidth = lineSize;
      this.widestLineNumber = this.lineCount;
    }
  }

  getLineCount(): number { return this.lineCount; }
  getMaxLineWidth(): number { return this.maxLineWidth; }
  getWidestLineNumber(): number { return this.widestLineNumber; }
  getLineWidthHistogram(): LineWidthHistogram { return this.lineWidthHistogram; }
  getMeanLineWidth(): number { return this.totalChars / this.lineCount; }

  getMedianLineWidth(): number {
    const sortedWidths = this.getSortedWidths();
    let cumulativeLineCount = 0;
    for (const width of sortedWidths) {
      cumulativeLineCount += this.lineWidthHistogram.getLinesForWidth(width).length;
      if (cumulativeLineCount > this.lineCount / 2) return width;
    }
    throw new Error('Cannot get here');
  }

  private getSortedWidths(): number[] {
    return Array.from(this.lineWidthHistogram.getWidths()).sort((a, b) => a - b);
  }
}

핵심 요약

• 포맷의 목적: 코드 포맷은 커뮤니케이션이다. 기능 구현보다 우선시해야 할 전문 개발자의 제1 원칙
• 파일 크기: 200줄 내외, 최대 500줄을 목표로. 작은 파일이 이해하기 쉽다
• 신문 은유: 파일명이 헤드라인, 위쪽이 고수준 개념, 아래로 갈수록 세부사항
• 수직 여백: 빈 줄은 개념의 분리를 나타내는 시각적 신호
• 수직 밀도: 밀접한 코드는 촘촘하게. 불필요한 주석이 밀접성을 파괴
• 수직 거리: 관련 개념은 가까이. caller는 callee 위에
• 수평 공백: 강하게 연관된 것은 붙이고, 약하게 연관된 것은 띄움
• 수평 정렬: 변수를 세로로 정렬하는 것은 잘못된 곳에 눈을 끌어 오히려 해가 됨
• 들여쓰기: 들여쓰기는 계층 구조를 시각화하는 핵심 도구. 짧아도 절대 생략하지 말 것
• 팀 규칙: 개인 선호보다 팀 합의가 우선. 일관성이 핵심

6장. 객체와 자료 구조

변수를 private으로 선언하는 데는 이유가 있다. 우리는 다른 누군가가 그것에 의존하길 원하지 않는다. 타입이나 구현을 언제든 자유롭게 바꿀 수 있길 원한다. 그렇다면 왜 그토록 많은 프로그래머들이 자동으로 getter/setter를 추가하여, private 변수를 마치 public인 양 노출시키는가?

데이터 추상화

• 구체적(Concrete) 구현 vs 추상적(Abstract) 인터페이스의 차이가 핵심
  • 아래 두 타입은 모두 2D 좌표를 표현하지만, 성격이 전혀 다름

// 나쁜 예: 구체적 Point - 직교 좌표계(rectangular)로 구현되었음이 명백히 드러남
class Point {
  public x: number;
  public y: number;
}

// 좋은 예: 추상적 Point - 직교 좌표계인지 극 좌표계인지 알 수 없음
interface Point {
  getX(): number;
  getY(): number;
  setCartesian(x: number, y: number): void;
  getR(): number;
  getTheta(): number;
  setPolar(r: number, theta: number): void;
}

• 추상적 Point가 우수한 이유

  • 내부가 직교 좌표계인지, 극 좌표계인지, 아예 다른 방식인지 알 수 없음
  • 인터페이스가 접근 정책(access policy) 을 강제함: 개별 좌표는 독립 읽기 가능하지만, 쓰기는 반드시 하나의 원자적 연산(setCartesian 또는 setPolar)으로만 가능
  • 구체적 Point는 변수가 private이고 getter/setter가 있더라도 구현이 노출되는 것과 마찬가지

• 연료 레벨 예시로 보는 추상화 수준

// 나쁜 예: 구현 세부사항 노출 - getter임이 명백
interface ConcreteVehicle {
  getFuelTankCapacityInGallons(): number;
  getGallonsOfGasoline(): number;
}

// 좋은 예: 데이터 형태를 전혀 알 수 없음
interface AbstractVehicle {
  getPercentFuelRemaining(): number;
}

• 핵심 인사이트
  • ==추상화는 단순히 인터페이스나 getter/setter를 씌우는 것이 아니다==
  • 객체가 담고 있는 데이터를 표현하는 최선의 방법에 대한 진지한 고민이 필요
  • 생각 없이 getter/setter를 추가하는 것은 최악의 선택

데이터/객체 비대칭

• 객체와 데이터 구조의 정의는 서로 정반대(virtual opposites)

  • 객체(Object): 데이터를 추상화 뒤에 숨기고, 데이터를 다루는 함수만 공개
  • 데이터 구조(Data Structure): 데이터를 공개하며, 의미 있는 함수가 없음

• 절차적(Procedural) 방식 예시

// 데이터 구조들: 행동 없이 데이터만 노출
interface Point { x: number; y: number; }

class Square { topLeft: Point; side: number; }
class Rectangle { topLeft: Point; height: number; width: number; }
class Circle { center: Point; radius: number; }

// 모든 행동은 Geometry에 집중
class Geometry {
  private readonly PI = Math.PI;

  area(shape: Square | Rectangle | Circle): number {
    if (shape instanceof Square) return shape.side ** 2;
    if (shape instanceof Rectangle) return shape.height * shape.width;
    if (shape instanceof Circle) return this.PI * shape.radius ** 2;
    throw new Error("Unknown shape");
  }
}

• 객체지향(OO) 방식 예시

interface Shape {
  area(): number;
}

class Square implements Shape {
  constructor(private topLeft: Point, private side: number) {}
  area(): number { return this.side ** 2; }
}

class Rectangle implements Shape {
  constructor(private topLeft: Point, private height: number, private width: number) {}
  area(): number { return this.height * this.width; }
}

class Circle implements Shape {
  constructor(private center: Point, private radius: number) {}
  area(): number { return Math.PI * this.radius ** 2; }
}

• 두 방식의 트레이드오프 비교

• 핵심 인사이트
  • “모든 것은 객체여야 한다”는 것은 미신이다
  • 새로운 데이터 타입을 추가할 가능성이 높을 때: OO 방식이 적합
  • 새로운 함수(동작) 를 추가할 가능성이 높을 때: 절차적 방식과 데이터 구조가 적합
  • 성숙한 프로그래머는 편견 없이 상황에 맞는 방식을 선택함

디미터 법칙

• 정의: 모듈은 자신이 조작하는 객체의 내부 구조를 알아서는 안 된다

  • 객체는 내부 구조를 accessor로 드러내지 않아야 함
  • 드러내는 순간 감추는 게 아니라 오히려 노출하는 것

• 메서드 f가 클래스 C 안에 있을 때, f는 다음 객체의 메서드만 호출할 수 있음

  1. C 자기 자신
  2. f가 직접 생성한 객체
  3. f의 인수로 전달된 객체
  4. C의 인스턴스 변수로 보유한 객체
  • 허용된 함수가 반환한 객체의 메서드는 호출하면 안 됨 - “친구에게만 말하고, 낯선 이에게는 말하지 마라”

기차 충돌

• 연쇄 호출(method chaining)은 기차 충돌처럼 보여 피해야 함

// 나쁜 예: 디미터 법칙 위반 가능성 높음
const outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();

// 개선: 각 단계를 분리
const opts = ctxt.getOptions();
const scratchDir = opts.getScratchDir();
const outputDir = scratchDir.getAbsolutePath();

• 그런데 이것도 디미터 위반인가?
  • ctxt, Options, ScratchDir이 객체라면: 내부 구조가 숨겨져야 하므로, 위 코드는 명백히 디미터 위반
  • ctxt, Options, ScratchDir이 데이터 구조라면: 내부 구조를 자연스럽게 드러내므로, 디미터 적용 대상이 아님
  • 만약 아래처럼 accessor 없이 작성됐다면 혼란 자체가 없었을 것

// 데이터 구조라면 이렇게 쓰는 것이 더 명확
const outputDir = ctxt.options.scratchDir.absolutePath;

• accessor 함수가 문제를 혼란스럽게 만든다
  • 데이터 구조는 public 변수만 갖고 함수가 없어야 함
  • 객체는 private 변수와 public 함수를 가져야 함
  • 하지만 “bean” 같은 프레임워크/표준이 단순 데이터 구조에도 accessor를 요구하면서 혼란이 생김

혼합체

• 혼합체: 절반은 객체, 절반은 데이터 구조인 최악의 설계

  • 의미 있는 함수도 있으면서, public 변수나 public getter/setter로 private 변수를 사실상 공개
  • 외부 함수가 데이터 구조처럼 내부 변수를 사용하도록 유혹함

• 혼합체의 문제점

  • 새로운 함수 추가도 어렵고, 새로운 데이터 타입 추가도 어려움
  • 양쪽의 단점만 모은 최악의 조합
  • 함수로부터 보호가 필요한지, 타입으로부터 보호가 필요한지 확신하지 못하는 혼란스러운 설계의 징후

구조 숨기기

• ctxt가 진짜 객체라면, 내부를 탐색하게 해서는 안 됨

// 나쁜 예 1: ctxt에 메서드가 폭발적으로 늘어남
ctxt.getAbsolutePathOfScratchDirectoryOption();

// 나쁜 예 2: getScratchDirectoryOption()이 객체가 아닌 데이터 구조를 반환한다고 가정
ctx.getScratchDirectoryOption().getAbsolutePath();

• 올바른 접근: 객체에게 “무엇을 하라”고 명령하라
  • 목적을 파악하라: 스크래치 디렉터리의 절대 경로가 필요했던 이유는 특정 이름의 스크래치 파일을 생성하기 위해서였음

// 좋은 예: ctxt에게 직접 작업을 시킴 - 내부 구조 노출 없음
const bos = ctxt.createScratchFileStream(classFileName);

데이터 전달 객체

• DTO의 정의: public 변수만 있고 함수가 없는 클래스 - 데이터 구조의 전형적인 형태

• DTO의 활용처

  • 데이터베이스와 통신할 때
  • 소켓으로부터 메시지를 파싱할 때
  • DB의 raw 데이터를 애플리케이션 코드의 객체로 변환하는 번역 단계의 첫 번째 단계로 활용

• Bean 형태: private 변수 + getter/setter 조합

  • OO 순수주의자들이 선호하지만, 실질적인 이점은 없음
  • getter/setter의 “유사 캡슐화(quasi-encapsulation)“는 기분만 좋게 할 뿐

// Bean 형태의 DTO 예시
class Address {
  constructor(
    private street: string,
    private streetExtra: string,
    private city: string,
    private state: string,
    private zip: string,
  ) {}

  getStreet(): string { return this.street; }
  getStreetExtra(): string { return this.streetExtra; }
  getCity(): string { return this.city; }
  getState(): string { return this.state; }
  getZip(): string { return this.zip; }
}

액티브 레코드

• Active Record: DTO의 특수한 형태

  • public(또는 bean 방식) 변수를 가지며, save()와 find() 같은 탐색용 메서드도 포함
  • 일반적으로 DB 테이블 또는 다른 데이터 소스와 직접 대응

• 흔한 실수: Active Record를 객체처럼 취급하는 것

  • 비즈니스 규칙 메서드를 Active Record에 추가하면 데이터 구조와 객체가 섞인 혼합체가 됨

• 올바른 사용법

  • Active Record는 데이터 구조로 취급
  • 비즈니스 규칙은 Active Record 인스턴스를 내부에 숨기는 별도의 객체에 위치시킴

// 잘못된 예: Active Record에 비즈니스 로직 혼재
class UserRecord {
  public id: number;
  public email: string;
  public password: string;

  save() { /* DB 저장 */ }
  find(id: number) { /* DB 조회 */ }

  // 비즈니스 로직이 여기 있으면 안 됨
  isEligibleForPremium(): boolean { /* ... */ }
}

// 좋은 예: 역할 분리
class UserRecord {
  public id: number;
  public email: string;
  public password: string;

  save() { /* DB 저장 */ }
  find(id: number) { /* DB 조회 */ }
}

class User {
  constructor(private record: UserRecord) {}

  isEligibleForPremium(): boolean { /* 비즈니스 로직만 */ }
}

정리

• 객체와 데이터 구조의 특성 요약

• 선택 기준

  • 새로운 데이터 타입의 유연성이 필요한 부분: 객체 선호
  • 새로운 행동(동작) 의 유연성이 필요한 부분: 데이터 구조와 절차적 코드 선호

• 핵심 인사이트

  • 좋은 개발자는 편견 없이 상황에 가장 적합한 접근 방식을 선택한다
  • 모든 것을 객체로 만들어야 한다는 강박을 버려라

핵심 요약

• 데이터 추상화: getter/setter만 추가한다고 추상화가 아니다. 데이터의 본질을 드러내는 인터페이스를 고민하라
• 객체 vs 데이터 구조: 두 개념은 정반대다. 상황에 맞게 골라 써라
• 절차적 vs OO 트레이드오프: OO는 타입 추가에 강하고, 절차적은 함수 추가에 강하다
• 디미터 법칙: 친구에게만 말하라. 반환된 객체의 메서드를 연쇄 호출하지 마라
• Train Wreck: 연쇄 메서드 호출은 객체의 내부를 너무 많이 알게 된다는 신호다
• 구조 숨기기: 객체에게 “이걸 해줘”라고 명령하라. 내부를 꺼내서 직접 처리하지 마라
• 혼합체(Hybrid): 객체와 데이터 구조의 나쁜 점만 모은 최악의 설계. 반드시 피하라
• DTO: 함수 없이 데이터만 노출하는 순수한 데이터 구조. DB 번역 첫 단계에 유용
• Active Record: DTO의 일종. 비즈니스 로직을 넣으면 혼합체가 된다. 별도 객체로 분리하라

7장. 오류 처리

에러 처리는 중요하다. 하지만 로직을 가린다면, 그것은 잘못된 것이다.

• 에러 처리는 프로그래밍에서 반드시 해야 하는 일
  • 입력이 비정상적일 수 있고, 디바이스가 실패할 수 있음
  • 문제가 발생했을 때 코드가 제 역할을 하도록 보장하는 것은 프로그래머의 책임
• 많은 코드베이스가 에러 처리 코드로 도배되어 있음
  • “도배”란 에러 처리가 전부라는 뜻이 아니라, 코드 여기저기에 흩어져 핵심 로직이 보이지 않는 상태를 의미
• 에러 처리는 별개의 관심사(Separate Concern)로 취급해야 한다
  • 비즈니스 로직과 에러 처리가 섞이면 코드가 복잡해지고 가독성이 떨어짐

반환 코드보다 예외를 사용하라

• 과거 방식: 리턴 코드 또는 에러 플래그
  • 에러 플래그를 세우거나, 호출자가 직접 확인해야 하는 에러 코드를 반환
  • 문제: 호출자 코드가 지저분해지고, 에러 체크를 잊어버리기 쉬움

// 나쁜 예: 리턴 코드 방식
function sendShutDown(): void {
  const handle = getHandle(DEV1);
  if (handle !== DeviceHandle.INVALID) {
    retrieveDeviceRecord(handle);
    if (record.getStatus() !== DEVICE_SUSPENDED) {
      pauseDevice(handle);
      clearDeviceWorkQueue(handle);
      closeDevice(handle);
    } else {
      logger.log("Device suspended. Unable to shut down");
    }
  } else {
    logger.log("Invalid handle for: " + DEV1.toString());
  }
}

• 개선 방식: 예외(Exception) 던지기
  • 에러가 발생하면 예외를 throw하면 호출 코드가 훨씬 깔끔해짐
  • 알고리즘(device shutdown)과 에러 처리가 분리되어 각각 독립적으로 이해 가능

// 좋은 예: 예외 방식
function sendShutDown(): void {
  try {
    tryToShutDown();
  } catch (e) {
    if (e instanceof DeviceShutDownError) {
      logger.log(e);
    }
  }
}

function tryToShutDown(): void {
  const handle = getHandle(DEV1);
  const record = retrieveDeviceRecord(handle);
  pauseDevice(handle);
  clearDeviceWorkQueue(handle);
  closeDevice(handle);
}

function getHandle(id: DeviceID): DeviceHandle {
  // ...
  throw new DeviceShutDownError("Invalid handle for: " + id.toString());
}

• 핵심 인사이트: 이건 단순히 미관의 문제가 아님. 두 가지 관심사(알고리즘, 에러 처리)가 분리되어 코드가 실질적으로 좋아지는 것

Try-Catch-Finally 문부터 작성하라

• try 블록은 트랜잭션(transaction) 과 같다
  • catch는 try 안에서 무슨 일이 있었든 프로그램을 일관된 상태(consistent state) 로 남겨야 함
• 예외를 던질 수 있는 코드를 작성할 때는 try-catch-finally부터 작성하라
  • try 블록의 트랜잭션 스코프를 먼저 정의함으로써, 호출자가 무엇을 기대해야 하는지 명확히 할 수 있음
• 권장 개발 순서 (TDD 방식)
  1. 예외가 발생하는 상황을 강제하는 테스트를 먼저 작성
  2. 테스트가 실패하도록 최소 구현 작성
  3. 예외를 실제로 던지도록 구현 수정
  4. 예외 타입을 점차 좁혀가며 리팩토링

// 1단계: 더미 구현 — 예외 없음 → 테스트 실패
function retrieveSection(sectionName: string): RecordedGrip[] {
  return [];
}

// 2단계: 실제 파일 접근 시도 → 예외 발생 → catch에서 래핑
function retrieveSection(sectionName: string): RecordedGrip[] {
  try {
    const stream = fs.createReadStream(sectionName);
    stream.close();
  } catch (e) {
    throw new StorageException("retrieval error", e as Error);
  }
  return [];
}

• 이렇게 하면 try 블록의 트랜잭션 스코프를 먼저 확보하고, 그 안의 세부 로직을 안전하게 채워나갈 수 있음

검사되지 않는 예외를 사용하라

• Checked Exception 논쟁은 끝났다 — Checked Exception은 득보다 실이 많다
• Checked Exception의 문제점: OCP(Open/Closed Principle) 위반
  • 저수준 함수에서 Checked Exception을 던지면, 그 함수를 호출하는 모든 상위 레벨 함수의 시그니처에 해당 예외가 선언되어야 함
  • 저수준 변경 하나가 연쇄적인 시그니처 변경을 전파시킴
  • 캡슐화 파괴: 예외를 통과시키는 모든 함수가 저수준 예외의 세부 사항을 알아야 함

저수준 함수 변경
  → 중간 레벨 함수 시그니처 변경
    → 상위 레벨 함수 시그니처 변경
      → ... (ad infinitum)

• C#, C++, Python, Ruby 모두 Checked Exception이 없지만 견고한 소프트웨어를 만들 수 있음
• 예외: 크리티컬한 라이브러리 작성 시에는 Checked Exception이 유용할 수 있음. 그러나 일반 애플리케이션 개발에서는 의존성 비용이 이점을 초과함
• TypeScript/Node.js는 애초에 Checked Exception 개념 자체가 없다 — 모든 예외는 Unchecked이므로 이 원칙을 자연스럽게 따를 수 있음

예외에 맥락을 제공하라

• 예외를 던질 때는 충분한 컨텍스트를 함께 제공해야 한다
  • 스택 트레이스만으로는 실패한 오퍼레이션의 의도를 알 수 없음
• 에러 메시지에 포함해야 할 것
  • 실패한 오퍼레이션이 무엇인지
  • 어떤 종류의 실패인지
  • 로깅에 충분한 정보

// 나쁜 예
throw new Error("failed");

// 좋은 예
throw new StorageException(
  `[FileStore.retrieveSection] 파일 읽기 실패 — sectionName: "${sectionName}", reason: ${(e as Error).message}`
);

호출자 관점으로 예외 클래스를 정의하라

• 에러를 분류하는 방법은 다양하지만 (출처별, 유형별), 가장 중요한 기준은 “어떻게 catch될 것인가” 이다
• 나쁜 예: 서드파티 예외를 그대로 여러 개 catch

// 나쁜 예: 중복된 처리, 서드파티 API에 강하게 결합
const port = new ACMEPort(12);
try {
  port.open();
} catch (e) {
  if (e instanceof DeviceResponseException) {
    reportPortError(e);
    logger.log("Device response exception", e);
  } else if (e instanceof ATM1212UnlockedException) {
    reportPortError(e);
    logger.log("Unlock exception", e);
  } else if (e instanceof GMXError) {
    reportPortError(e);
    logger.log("Device response exception");
  }
}

• 좋은 예: 서드파티 API를 래핑하여 공통 예외 타입으로 변환

// 호출하는 쪽이 훨씬 깔끔해짐
const port = new LocalPort(12);
try {
  port.open();
} catch (e) {
  if (e instanceof PortDeviceFailure) {
    reportError(e);
    logger.log(e.message, e);
  }
}

// 래퍼 클래스: 모든 서드파티 예외를 단일 예외로 변환
class LocalPort {
  private innerPort: ACMEPort;

  constructor(portNumber: number) {
    this.innerPort = new ACMEPort(portNumber);
  }

  open(): void {
    try {
      this.innerPort.open();
    } catch (e) {
      throw new PortDeviceFailure(e as Error);
    }
  }
}

• 서드파티 API 래핑의 장점
  • 서드파티 의존성 최소화 → 나중에 라이브러리를 교체해도 영향 범위가 래퍼 하나에 한정됨
  • 테스트 시 서드파티 호출을 mock하기 쉬워짐
  • 특정 벤더의 API 설계 결정에 종속되지 않음 → 편안한 인터페이스를 직접 정의 가능
• 한 영역의 코드에는 단일 예외 클래스 하나로 충분한 경우가 많음
  • 예외를 구분해야 할 경우는, 특정 예외만 catch하고 나머지는 통과시켜야 할 때뿐

정상 흐름을 정의하라

• 앞선 조언들을 따르면 비즈니스 로직과 에러 처리가 잘 분리됨
• 하지만 때로는 중단(abort)하지 않는 것이 더 나은 경우가 있음
• 나쁜 예: 예외가 정상 흐름 로직을 오염시키는 경우

// 나쁜 예
try {
  const expenses = expenseReportDAO.getMeals(employee.getID());
  totalAmount += expenses.getTotal();
} catch (e) {
  if (e instanceof MealExpensesNotFound) {
    totalAmount += getMealPerDiem();
  }
}

• Special Case Pattern (Fowler)
  • 예외 대신, 특수 케이스를 처리하는 객체나 클래스를 만들어 클라이언트 코드가 예외적 동작을 다룰 필요가 없게 함
  • 예외적 동작이 Special Case 객체 내부에 캡슐화됨

// 좋은 예: Special Case Pattern
// DAO는 항상 유효한 MealExpenses 객체를 반환함
const expenses = expenseReportDAO.getMeals(employee.getID());
totalAmount += expenses.getTotal(); // 예외 없이 항상 동작

// 식비가 없을 때 반환되는 Special Case 객체
class PerDiemMealExpenses implements MealExpenses {
  getTotal(): number {
    return PER_DIEM_AMOUNT; // 기본 일비 반환
  }
}

null을 반환하지 마라

• null을 반환하는 것은 스스로 일을 만드는 것이며, 호출자에게 문제를 떠넘기는 것
  • null 체크를 하나라도 빠뜨리면 앱이 통제 불능 상태가 됨

// 나쁜 예: null 반환의 지옥
function registerItem(item: Item | null): void {
  if (item !== null) {
    const registry = persistentStore.getItemRegistry();
    if (registry !== null) {
      const existing = registry.getItem(item.getID());
      // existing이 null이면? → 런타임 에러!
      if (existing.getBillingPeriod().hasRetailOwner()) {
        existing.register(item);
      }
    }
  }
}

• null을 반환하고 싶다면, 대신 예외를 던지거나 Special Case 객체를 반환하라
• 컬렉션은 null 대신 빈 배열을 반환하라

// 나쁜 예
function getEmployees(): Employee[] | null {
  if (/* 직원 없음 */) return null;
}

// 좋은 예: 빈 배열 반환
function getEmployees(): Employee[] {
  if (/* 직원 없음 */) return [];
}

// 호출하는 쪽이 훨씬 깔끔해짐
const employees = getEmployees();
for (const e of employees) {
  totalPay += e.getPay();
}

• 핵심 인사이트: null 체크가 너무 많은 코드의 문제는 null 체크가 부족한 것이 아니라 너무 많다는 것. null을 애초에 반환하지 않으면 해결됨

null을 전달하지 마라

• null을 반환하는 것보다 null을 인수로 전달하는 것이 더 나쁘다
  • API가 명시적으로 null을 기대하는 경우가 아니라면, 기본적으로 null 전달을 금지해야 함

// 나쁜 예: null을 전달하면 런타임 에러
class MetricsCalculator {
  xProjection(p1: Point, p2: Point): number {
    return (p2.x - p1.x) * 1.5;
  }
}
calculator.xProjection(null as any, new Point(12, 13)); // 런타임 에러!

// 좋은 예: TypeScript strict 모드로 null 전달 자체를 컴파일 타임에 차단
class MetricsCalculator {
  xProjection(p1: Point, p2: Point): number {
    // p1, p2는 Point 타입이므로 null 전달 시 컴파일 에러 발생
    return (p2.x - p1.x) * 1.5;
  }
}

• 대응 방법 비교

• 핵심 인사이트: 대부분의 언어는 실수로 null이 전달되었을 때 우아하게 처리하는 방법이 없다. 따라서 기본 정책으로 null 전달을 금지하는 것이 합리적. TypeScript의 strict: true + strictNullChecks는 이 원칙을 언어 차원에서 강제함

정리

• 깨끗한 코드는 읽기 쉬워야 하지만, 동시에 견고해야 한다
• 이 두 가지는 상충하지 않는다
• 에러 처리를 주요 로직과 별개의 관심사로 볼 수 있다면, 독립적으로 추론할 수 있고 코드 유지보수성이 크게 향상된다

핵심 요약

• Return Code 금지: 리턴 코드 대신 예외를 사용하라. 로직과 에러 처리가 분리된다
• try-catch-finally 먼저: 예외 가능 코드는 트랜잭션 스코프부터 정의하라
• Unchecked Exception 선호: Checked Exception은 OCP를 위반하고 캡슐화를 파괴한다
• 예외 컨텍스트 제공: 실패한 오퍼레이션과 실패 유형을 메시지에 담아라
• 호출자 관점의 예외 정의: 예외는 어떻게 catch될 것인가를 기준으로 정의하라
• 서드파티 API 래핑: 의존성을 최소화하고 테스트 용이성을 높여라
• Special Case Pattern: 예외 대신 특수 케이스를 처리하는 객체를 반환하라
• null 반환 금지: null 대신 예외 또는 빈 컬렉션/Special Case 객체를 반환하라
• null 전달 금지: null 전달은 기본 금지. TypeScript strictNullChecks로 강제 가능

8장. 경계

우리는 시스템 내의 모든 소프트웨어를 직접 통제하지 못한다. 서드파티 패키지를 구매하거나 오픈소스를 사용하기도 하고, 사내 다른 팀이 만든 컴포넌트에 의존하기도 한다. 이 외부 코드를 우리 코드와 깔끔하게 통합하는 것이 이 챕터의 핵심 주제다.

• 소프트웨어 경계란 우리가 통제할 수 있는 코드와 그렇지 않은 코드 사이의 접점
• 경계를 깔끔하게 유지하지 않으면 외부 코드의 변화가 내부 코드 전체로 전파됨
• 이 챕터는 경계를 깨끗하게 유지하기 위한 실천법과 기법들을 다룸

서드파티 코드 사용

• 인터페이스 제공자 vs 사용자 사이의 긴장 관계

  • 제공자: 최대한 넓은 환경에서 동작하도록 범용적인 인터페이스를 만들려 함
  • 사용자: 자신의 특정 필요에 맞는 집중된 인터페이스를 원함
  • 이 긴장 관계가 경계에서 문제를 일으킴

• 서드파티 인터페이스를 직접 노출할 때의 위험성

  • 예: TypeScript의 Map<string, Sensor>를 시스템 전체에 넘겨다닌다고 가정

// 나쁜 예: Map을 직접 노출하고 전달
const sensors = new Map<string, Sensor>();

// 코드 곳곳에서 이런 코드가 반복됨
const s = sensors.get(sensorId) as Sensor;

• Map이 가진 clear(), delete() 등 불필요한 메서드까지 외부에 노출됨

• 어디서든 Map의 내용을 임의로 삭제하거나 잘못된 타입을 삽입할 수 있음

• Map 인터페이스가 변경되면 시스템 전체의 수많은 지점을 수정해야 함

  • 실제로 TypeScript/JavaScript 생태계에서도 이런 변경은 충분히 발생 가능

• 경계 인터페이스를 감싸는 클린한 방법

// 좋은 예: 경계 인터페이스를 클래스 내부에 숨김
class Sensors {
  private readonly sensors = new Map<string, Sensor>();

  getById(id: string): Sensor | undefined {
    return this.sensors.get(id);
  }

  add(id: string, sensor: Sensor): void {
    this.sensors.set(id, sensor);
  }

  // 애플리케이션에 필요한 메서드만 노출
}

• Map이라는 경계 인터페이스가 클래스 내부에 완전히 숨겨짐

• Map 내부 구현이 바뀌어도 영향을 받는 지점이 Sensors 클래스 하나뿐

• 타입 캐스팅 등 타입 관리가 한 곳에서 이루어짐

• 애플리케이션의 필요에 맞게 인터페이스가 제한되고 설계/비즈니스 규칙을 강제할 수 있음

• 핵심 규칙

  • Map과 같은 경계 인터페이스를 사용한다면, 그것을 사용하는 클래스 내부에만 두어야 함
  • 경계 인터페이스를 public API의 반환값이나 인자로 노출하지 말 것
  • 모든 Map 사용을 무조건 래핑하라는 뜻이 아니라, 시스템 전반에 넘겨다니지 말라는 것

경계 탐색과 학습

• 서드파티 코드를 처음 사용할 때의 일반적인 접근 방식의 문제점

  • 문서를 읽고, 실제 프로덕션 코드에 바로 통합한 뒤 디버깅
  • 버그가 우리 코드에 있는지 서드파티 코드에 있는지 알기 어려움
  • 학습과 통합을 동시에 하는 것은 이중으로 어렵다

• 학습 테스트(Learning Tests) — Jim Newkirk가 명명

  • 프로덕션 코드에 서드파티 코드를 바로 통합하는 대신, 테스트 코드로 먼저 탐색
  • 서드파티 API를 실제 사용할 방식으로 호출하는 통제된 실험
  • API에서 원하는 동작에만 집중한 단순한 단위 테스트들

• 학습 테스트 예시: log4j 대신 TypeScript 기반의 winston 라이브러리 탐색

// 1단계: 단순히 콘솔에 출력되는지 확인
test('basicLogger', () => {
  const logger = winston.createLogger({
    transports: [new winston.transports.Console()],
  });
  logger.info('hello');
  // 에러 없이 실행되는지 확인
});

// 2단계: 포맷 설정 확인
test('loggerWithFormat', () => {
  const logger = winston.createLogger({
    format: winston.format.combine(
      winston.format.timestamp(),
      winston.format.simple()
    ),
    transports: [new winston.transports.Console()],
  });
  logger.info('hello with format');
});

// 3단계: 파일 전송 확인
test('loggerWithFileTransport', () => {
  const logger = winston.createLogger({
    transports: [new winston.transports.File({ filename: 'test.log' })],
  });
  logger.warn('warn message');
});

• 이렇게 단계적으로 탐색하며 라이브러리의 동작 방식을 정확히 이해하고 지식을 코드에 인코딩함
• 이후 이 지식을 우리 자체 로거 클래스로 캡슐화하여 나머지 앱이 서드파티 경계에서 격리됨

학습 테스트는 무료 이상이다

• 비용 관점

  • 어차피 API를 학습해야 하므로, 학습 테스트는 추가 비용이 거의 없음
  • 테스트를 통한 학습은 독립적이고 통제된 방식이라 오히려 더 효율적

• 투자 수익(ROI) 관점에서 긍정적인 이유

  • 서드파티 패키지의 새 버전이 릴리즈될 때마다 학습 테스트를 실행하여 동작 변경 여부를 즉시 감지 가능
  • 우리가 기대하는 방식으로 서드파티 코드가 동작하는지 지속적으로 검증함
  • 서드파티 코드가 우리 요구사항과 호환되지 않는 방식으로 변경되면 즉시 파악

• 경계 테스트(Boundary Tests)의 필요성

  • 학습 테스트가 필요 없더라도, 경계 테스트 세트는 반드시 유지해야 함
  • 경계 테스트 없이는 구버전에 더 오래 머물려는 유혹에 빠지기 쉬움
  • 경계 테스트가 있어야 새 버전으로의 마이그레이션이 안전하고 용이해짐

아직 존재하지 않는 코드 사용

• 또 다른 종류의 경계: 알려진 것과 알려지지 않은 것 사이

  • 코드의 특정 지점에서 우리의 지식이 끊기는 경우가 있음
  • 경계 너머에 무엇이 있는지 현재로서는 알 수 없는 상황

• 실제 사례: 라디오 통신 시스템의 Transmitter 서브시스템

  • 개발팀은 “Transmitter” 서브시스템에 대해 아는 것이 없었고, 담당 팀은 아직 인터페이스를 정의하지 않은 상태
  • 미지의 영역 때문에 개발이 블로킹되는 상황을 원하지 않음

• 해결책: 원하는 인터페이스를 먼저 직접 정의

// 우리가 원하는 인터페이스를 먼저 직접 정의
interface Transmitter {
  transmit(frequency: number, stream: DataStream): void;
}

// 테스트용 Fake 구현체
class FakeTransmitter implements Transmitter {
  transmit(frequency: number, stream: DataStream): void {
    // 테스트 목적의 가짜 구현
  }
}

// 실제 API가 정의된 후 Adapter 작성
class TransmitterAdapter implements Transmitter {
  constructor(private readonly realApi: RealTransmitterAPI) {}

  transmit(frequency: number, stream: DataStream): void {
    // 실제 API의 호출 방식에 맞게 변환하여 위임
    this.realApi.setFrequency(frequency);
    this.realApi.sendData(stream.read());
  }
}

• 이 설계의 장점

classDiagram
    class CommunicationController {
    }
    class Transmitter {
        <<interface>>
        +transmit(frequency, stream)
    }
    class FakeTransmitter {
        +transmit(frequency, stream)
    }
    class TransmitterAdapter {
        +transmit(frequency, stream)
    }
    class RealTransmitterAPI {
        <<future>>
    }

    CommunicationController --> Transmitter
    FakeTransmitter ..|> Transmitter
    TransmitterAdapter ..|> Transmitter
    TransmitterAdapter --> RealTransmitterAPI

• CommunicationController는 실제 Transmitter API로부터 완전히 격리됨
• 인터페이스가 우리 통제 하에 있으므로 클라이언트 코드가 더 읽기 쉽고 집중적
• TransmitterAdapter가 실제 API와의 상호작용을 캡슐화 — API가 바뀌어도 수정 지점이 하나
• FakeTransmitter를 사용해 CommunicationController를 독립적으로 테스트 가능 (편리한 테스트 이음새 확보)
• 실제 API가 나온 이후에는 경계 테스트를 작성하여 API를 올바르게 사용하는지 검증

깨끗한 경계

• 경계에서 흥미로운 일이 일어난다 — 특히 변경

  • 좋은 소프트웨어 설계는 큰 투자나 재작업 없이 변경을 수용함
  • 통제 밖의 코드를 사용할 때는 투자를 보호하고 미래 변경 비용을 최소화하는 특별한 주의가 필요

• 핵심 원칙: 서드파티 세부 사항을 아는 코드를 최소화하라

  • 통제할 수 있는 것에 의존하는 것이 통제할 수 없는 것에 의존하는 것보다 낫다
  • 통제할 수 없는 것에 너무 많이 의존하면, 결국 그것이 우리를 통제하게 됨

• 서드파티 경계를 관리하는 두 가지 기법

• 경계를 깨끗하게 유지하면 얻는 것
  • 코드가 더 명확하게 이야기를 전달함
  • 경계를 넘나드는 사용이 내부적으로 일관성을 갖게 됨
  • 서드파티 코드가 변경될 때 유지보수 지점이 최소화됨

핵심 요약

• 서드파티 코드 사용: 경계 인터페이스(Map 등)를 시스템 전반에 넘기지 말고 클래스 내부에 숨길 것
• 학습 테스트: 프로덕션 코드 대신 테스트로 서드파티 API를 먼저 탐색하라 — 무료 이상의 가치가 있다
• 경계 테스트: 서드파티 패키지 신버전 출시 시 호환성 감지를 위해 경계 테스트를 항상 유지하라
• 미존재 코드 사용: 원하는 인터페이스를 먼저 직접 정의하고, Adapter로 실제 API와 연결하라
• 깨끗한 경계: 통제 불가능한 것에 의존하는 코드를 최소화하라 — 래핑 또는 어댑터로 관리하라
• 변경 비용: 경계를 잘 관리하면 서드파티 변경이 일어나도 수정 지점이 최소화된다

9장. 단위 테스트

테스트 코드는 프로덕션 코드만큼 중요하다. 테스트가 없으면 코드는 썩는다.

• 1997년에는 TDD를 아는 사람이 없었음. 유닛 테스트는 프로그램이 “동작하는지” 확인하는 임시 코드에 불과했음
• 당시의 테스트 방식: 클래스와 메서드를 작성한 뒤, 수동으로 상호작용하는 간단한 드라이버 프로그램을 임시로 만들어 확인
• 저자의 과거 경험 사례
  • 임베디드 실시간 시스템의 타이머 기능을 테스트하기 위해 키보드 입력을 5초 뒤에 화면에 재생하는 드라이버를 직접 만들어 멜로디를 타이핑하며 육안으로 확인
  • 확인 후 테스트 코드를 버렸음
• 현재의 기준: 코드의 모든 구석을 자동화된 테스트로 검증하고, 타이밍 함수를 모킹하여 OS로부터 코드를 격리하며, 테스트와 프로덕션 코드를 같은 소스 패키지에 함께 커밋함
• 핵심 인사이트: Agile과 TDD 운동 덕분에 자동화된 유닛 테스트를 작성하는 개발자가 늘었지만, 좋은 테스트를 작성하는 더 섬세하고 중요한 포인트들을 놓치는 경우가 많음

TDD의 세 가지 법칙

TDD는 단순히 “프로덕션 코드 전에 테스트를 먼저 작성하라”는 규칙이 전부가 아님. 세 가지 법칙이 존재함.

• 세 법칙은 약 30초 단위의 사이클로 테스트와 프로덕션 코드를 함께 작성하도록 강제함
• 이 방식대로 하면 하루에 수십 개, 한 달에 수백 개, 1년에 수천 개의 테스트가 쌓임
• 테스트 코드의 양이 프로덕션 코드에 맞먹을 수 있어 관리 부담이 발생할 수 있음

테스트를 깨끗하게 유지하기

지저분한 테스트의 위험성

• 일부 팀은 테스트 코드에 “빠르고 더럽게(Quick and Dirty)” 원칙을 적용함
  • 변수명이 불명확해도 됨
  • 함수가 짧고 서술적일 필요 없음
  • 설계가 엉망이어도 동작하면 됨
• 이는 치명적인 오판이다: 지저분한 테스트를 갖는 것은 테스트가 없는 것과 같거나 오히려 더 나쁨

지저분한 테스트가 만드는 악순환

graph TD
    A[지저분한 테스트 코드] --> B[프로덕션 코드 변경 시 테스트도 변경 필요]
    B --> C[테스트 변경 비용이 너무 커짐]
    C --> D[테스트 suite 폐기]
    D --> E[변경에 대한 두려움 발생]
    E --> F[프로덕션 코드 정리 중단]
    F --> G[프로덕션 코드 부패]
    G --> H[결함 증가, 고객 불만]

• 프로덕션 코드가 변하면 테스트도 함께 변해야 함
• 테스트 코드가 더러울수록 변경 비용이 증가함
• 결국 테스트 suite 전체를 폐기하게 되고, 이는 변경에 대한 안전망을 잃는 것을 의미함
• 교훈: 테스트 코드는 프로덕션 코드와 동일한 수준의 품질이 필요함

핵심 원칙

테스트 코드는 일급 시민이다. 사고, 설계, 주의가 필요하며 프로덕션 코드만큼 깨끗하게 유지되어야 한다.

테스트가 여러 특성을 가능하게 한다

• 테스트를 깨끗하게 유지하지 않으면 테스트를 잃게 되고, 그러면 프로덕션 코드를 유연하게 유지해주는 것도 잃게 됨
• 유닛 테스트가 코드를 유연하고(Flexible), 유지보수 가능하고(Maintainable), 재사용 가능하게(Reusable) 만든다
• 테스트가 있으면 코드 변경이 두렵지 않음. 버그를 바로 발견할 수 있기 때문
• 테스트가 없으면 모든 변경이 잠재적 버그임. 아키텍처가 아무리 유연하고 설계가 아무리 깔끔해도 마찬가지
• 테스트 커버리지가 높을수록 두려움이 줄어든다
  • 구조가 좋지 않은 코드도 거의 제약 없이 변경 가능
  • 아키텍처와 설계를 두려움 없이 개선할 수 있음
• 테스트가 더러우면 코드 변경 능력이 저하되고, 결국 코드도 부패함

깨끗한 테스트

깨끗한 테스트의 핵심

가독성, 가독성, 가독성. 가독성은 프로덕션 코드에서보다 테스트에서 더 중요하다.

• 깨끗한 테스트를 만드는 것: 명확성(Clarity), 단순성(Simplicity), 표현의 밀도(Density of expression)
• 테스트에서는 최소한의 표현으로 많은 것을 전달해야 함

나쁜 테스트 예시 vs 좋은 테스트 예시

Before: 세부 구현이 테스트의 의도를 가리는 경우

// 나쁜 예 - 불필요한 세부사항이 가독성을 해침
test('getPageHierarchyAsXml', async () => {
  await crawler.addPage(root, PathParser.parse('PageOne'));
  await crawler.addPage(root, PathParser.parse('PageOne.ChildOne'));
  await crawler.addPage(root, PathParser.parse('PageTwo'));

  request.setResource('root');
  request.addInput('type', 'pages');

  const responder = new SerializedPageResponder();
  const response = await responder.makeResponse(new FitNesseContext(root), request);

  const xml = response.getContent();
  expect(response.getContentType()).toBe('text/xml');
  expect(xml).toContain('<name>PageOne</name>');
  expect(xml).toContain('<name>PageTwo</name>');
  expect(xml).toContain('<name>ChildOne</name>');
});