책노트: A Philosophy of Software Design 6장 - 두 번 설계하고, 이유를 남겨라

A Philosophy of Software Design 6장 - 두 번 설계하고, 이유를 남겨라

A Philosophy of Software Design는 설계를 거창한 아키텍처 선언보다 일상적인 복잡성 관리로 읽게 만든다. 이 6회차의 범위는 Chapter 11 Design it Twice, Chapter 12 Why Write Comments? The Four Excuses이다. 원문을 길게 옮기기보다, 공개 글에서는 핵심 개념을 짧은 문구와 내 언어의 요약으로만 다룬다.

이번 글의 질문은 이것이다. 첫 번째 설계안을 의심하지 않으면 어떤 가능성을 잃는가?

■ 이 노트의 사용법

이 글은 10회로 읽는 A Philosophy of Software Design 시리즈의 6회차다. 범위는 Chapter 11 Design it Twice, Chapter 12 Why Write Comments? The Four Excuses이다.

포착 -> 증류 -> 연결 -> 표현 4단계 깔때기로 기술서를 흘려보낸다. 핵심 원칙은 같다. 책 노트는 창고, 인사이트 카드는 화폐.

L0 · 서지 & 진입

• 한 문장 핵심: 설계 대안 비교와 좋은 주석은 모두 보이지 않는 이유를 드러내는 장치다.
• 이 책을 든 이유 / 기대한 질문: AI 도구와 자동화가 코드를 더 빨리 만들수록, 어떤 코드가 오래 이해되고 수정될 수 있는지 묻고 싶다.
• 읽기 전 가설: 주석은 코드 뒤에 붙는 설명으로 취급되기 쉽다. 이 범위는 주석을 설계 이유를 보존하는 도구로 끌어올린다.
• 저자 한 줄 컨텍스트: John Ousterhout는 운영체제와 분산 시스템 연구, Tcl/Tk 개발, Stanford 강의를 통해 소프트웨어 설계 교육을 이어온 컴퓨터 과학자다.
• 이번 회차 범위: Chapter 11 Design it Twice, Chapter 12 Why Write Comments? The Four Excuses
• 관련 도서 / 계보: The Pragmatic Programmer · Refactoring · Clean Code · Software Architecture

L1 · 포착함

“ 짧은 문구 · #design

“design it twice”

• 왜 표시했나: 첫 설계안을 기준이 아니라 후보로 취급한다. ^q01
• 내 반응: 대안을 만들면 숨은 가정이 드러난다.

“ 짧은 문구 · #design

“self-documenting”

• 왜 표시했나: 좋은 코드가 모든 설명을 대신한다는 흔한 변명이다. ^q02
• 내 반응: 명확한 코드는 필요하지만 의도와 맥락까지 항상 말하지는 않는다.

“ 짧은 문구 · #design

“well-written comments”

• 왜 표시했나: 코드에서 보이지 않는 정보를 남기는 주석이다. ^q03
• 내 반응: 좋은 주석은 중복 설명이 아니라 판단의 보존이다.

■ 저작권 경계

이 공개 노트는 책의 장문 문장을 재현하지 않는다. 장 제목과 짧은 핵심어만 단서로 삼고, 내용은 요약·해석·적용 중심으로 재구성한다.

L2 · 챕터 지도

#	범위	한 줄 요약	핵심 주장 1개	기억할 위치
1	두 번 설계	최소 두 가지 설계안을 비교한다	비교가 있어야 장단점이 보인다	^q01
2	첫안의 위험	처음 떠오른 구조는 익숙함의 산물일 수 있다	설계는 생성보다 비교에서 좋아진다	^q02
3	주석 변명	시간 없음, 자기문서화, 낡은 주석, 무가치한 주석이라는 변명을 검토한다	나쁜 주석은 주석 자체의 실패가 아니다	^q03
4	좋은 주석의 이익	추상화, 의도, 제약을 저장한다	미래 독자는 코드보다 이유를 찾는다

이번 회차 논증 한 단락:

설계 대안 비교와 좋은 주석은 모두 보이지 않는 이유를 드러내는 장치다. 주석은 코드 뒤에 붙는 설명으로 취급되기 쉽다. 이 범위는 주석을 설계 이유를 보존하는 도구로 끌어올린다. 이 범위를 설계 실무에 적용하면, 코드 리뷰의 질문이 “작동하는가”에서 “다음 변경자가 무엇을 알아야 하는가”로 이동한다. 설계는 별도의 의식이 아니라 매일의 이름, 경계, 예외, 주석, 계층 선택 속에 들어 있다.

L3 · 인사이트 카드 색인

• A Philosophy of Software Design - I6.1 첫 설계안은 정답이 아니라 비교를 시작하기 위한 샘플이다
• A Philosophy of Software Design - I6.2 주석은 코드의 반복이 아니라 설계 판단의 장기 기억이다
• A Philosophy of Software Design - I6.3 좋은 코드와 좋은 주석은 경쟁 관계가 아니라 서로 다른 정보를 맡는다

L4 · 생산 보드

■ 출력 파이프라인

• 블로그 초안: 6회차를 “두 번 설계하고, 이유를 남겨라” 관점으로 정리
• 코드 리뷰 질문: 첫 번째 설계안을 의심하지 않으면 어떤 가능성을 잃는가?
• 인사이트 카드: 첫 설계안은 정답이 아니라 비교를 시작하기 위한 샘플이다
• 적용 실험: 최근 수정한 모듈 하나에 이 회차의 기준을 적용해 보기

L5 · 연결 & 복습

• 다른 책/아이디어와의 연결: Architecture Decision Record와 연결된다. 코드 가까이에 남는 짧은 이유와 별도 결정 기록은 서로 보완될 수 있다.
• 미해결 질문:
  • 지금 내 코드베이스에서 이 회차의 레드플래그는 어디에 가장 뚜렷하게 보이는가?
  • AI 에이전트가 코드를 작성할 때 이 원칙을 검증 루프로 넣으려면 어떤 체크가 필요할까?
• 복습 일정: 1주 □ / 1개월 □ / 3개월 □
• 한 문장 최종 정리: 설계의 품질은 첫 아이디어의 반짝임보다 대안을 비교하고 이유를 남기는 습관에서 나온다.