책노트: A Philosophy of Software Design 7장 - 주석과 이름은 의도를 전달해야 한다

A Philosophy of Software Design 7장 - 주석과 이름은 의도를 전달해야 한다

A Philosophy of Software Design는 설계를 거창한 아키텍처 선언보다 일상적인 복잡성 관리로 읽게 만든다. 이 7회차의 범위는 Chapter 13 Comments Should Describe Things That Aren’t Obvious from the Code, Chapter 14 Choosing Names이다. 원문을 길게 옮기기보다, 공개 글에서는 핵심 개념을 짧은 문구와 내 언어의 요약으로만 다룬다.

이번 글의 질문은 이것이다. 읽는 사람은 코드에서 무엇을 이미 알고, 무엇을 따로 배워야 하는가?

■ 이 노트의 사용법

이 글은 10회로 읽는 A Philosophy of Software Design 시리즈의 7회차다. 범위는 Chapter 13 Comments Should Describe Things That Aren’t Obvious from the Code, Chapter 14 Choosing Names이다.

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

L0 · 서지 & 진입

• 한 문장 핵심: 좋은 주석과 좋은 이름은 기계가 실행하는 절차가 아니라 사람이 가져야 할 모델을 만든다.
• 이 책을 든 이유 / 기대한 질문: AI 도구와 자동화가 코드를 더 빨리 만들수록, 어떤 코드가 오래 이해되고 수정될 수 있는지 묻고 싶다.
• 읽기 전 가설: 주석과 이름을 스타일 취향으로 보면 설계 도구로 쓰지 못한다. 이 범위는 표현을 인터페이스의 일부로 본다.
• 저자 한 줄 컨텍스트: John Ousterhout는 운영체제와 분산 시스템 연구, Tcl/Tk 개발, Stanford 강의를 통해 소프트웨어 설계 교육을 이어온 컴퓨터 과학자다.
• 이번 회차 범위: Chapter 13 Comments Should Describe Things That Aren’t Obvious from the Code, Chapter 14 Choosing Names
• 관련 도서 / 계보: The Pragmatic Programmer · Refactoring · Clean Code · Software Architecture

L1 · 포착함

“ 짧은 문구 · #design

“don’t repeat the code”

• 왜 표시했나: 주석이 코드의 낮은 수준 동작을 되풀이하면 가치가 낮다. ^q01
• 내 반응: 반복 설명은 유지보수 비용만 늘린다.

“ 짧은 문구 · #design

“interface documentation”

• 왜 표시했나: 사용자가 알아야 할 계약과 기대를 설명한다. ^q02
• 내 반응: 인터페이스 주석은 사용자의 사고 모델을 만든다.

“ 짧은 문구 · #design

“precise names”

• 왜 표시했나: 이름이 정확할수록 별도 설명이 줄어든다. ^q03
• 내 반응: 이름은 짧은 문서이자 작은 추상화다.

■ 저작권 경계

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

L2 · 챕터 지도

#	범위	한 줄 요약	핵심 주장 1개	기억할 위치
1	주석 관례	무엇을 어디에 쓸지 팀의 기준을 정한다	일관된 주석은 찾기 쉽고 유지하기 쉽다	^q01
2	코드 반복 금지	보이는 절차보다 보이지 않는 이유를 설명한다	주석은 코드가 말하지 않는 정보를 맡는다	^q02
3	낮은 수준 주석	정밀한 세부 의미를 보충한다	복잡한 식이나 조건의 의도를 밝힌다	^q03
4	높은 수준 주석	전체 흐름의 직관을 만든다	파일과 모듈 수준에서 독자의 길을 잡는다
5	이름 짓기	정확한 이미지를 만드는 단어를 고른다	모호한 이름은 버그의 토양이 된다

이번 회차 논증 한 단락:

좋은 주석과 좋은 이름은 기계가 실행하는 절차가 아니라 사람이 가져야 할 모델을 만든다. 주석과 이름을 스타일 취향으로 보면 설계 도구로 쓰지 못한다. 이 범위는 표현을 인터페이스의 일부로 본다. 이 범위를 설계 실무에 적용하면, 코드 리뷰의 질문이 “작동하는가”에서 “다음 변경자가 무엇을 알아야 하는가”로 이동한다. 설계는 별도의 의식이 아니라 매일의 이름, 경계, 예외, 주석, 계층 선택 속에 들어 있다.

L3 · 인사이트 카드 색인

• A Philosophy of Software Design - I7.1 주석은 코드가 말하지 못하는 의도와 제약을 맡아야 한다
• A Philosophy of Software Design - I7.2 이름은 짧은 문서이므로 추상화의 정확도를 결정한다
• A Philosophy of Software Design - I7.3 인터페이스 문서화는 사용법 설명이 아니라 사고 모델 설계다

L4 · 생산 보드

■ 출력 파이프라인

• 블로그 초안: 7회차를 “주석과 이름은 의도를 전달해야 한다” 관점으로 정리
• 코드 리뷰 질문: 읽는 사람은 코드에서 무엇을 이미 알고, 무엇을 따로 배워야 하는가?
• 인사이트 카드: 주석은 코드가 말하지 못하는 의도와 제약을 맡아야 한다
• 적용 실험: 최근 수정한 모듈 하나에 이 회차의 기준을 적용해 보기

L5 · 연결 & 복습

• 다른 책/아이디어와의 연결: 클린 코드의 이름 짓기 원칙과 연결되지만, 이 책은 특히 이름이 추상화 경계를 만든다는 점을 강조한다.
• 미해결 질문:
  • 지금 내 코드베이스에서 이 회차의 레드플래그는 어디에 가장 뚜렷하게 보이는가?
  • AI 에이전트가 코드를 작성할 때 이 원칙을 검증 루프로 넣으려면 어떤 체크가 필요할까?
• 복습 일정: 1주 □ / 1개월 □ / 3개월 □
• 한 문장 최종 정리: 좋은 이름과 주석은 코드를 꾸미는 문장이 아니라 독자가 올바른 모델을 갖게 하는 설계 표면이다.