Codebase Design

Codebase Design

deep module을 설계한다: 작은 인터페이스 뒤에 많은 동작, 깨끗한 seam에 놓이고, 그 인터페이스를 통해 테스트된다. 코드를 설계하거나 재구성하는 모든 자리에서 이 언어와 원칙을 쓴다. 목표는 호출자에게 leverage, 유지보수자에게 locality, 모두에게 testability다. 에이전트는 코딩을 가속하는 만큼 엔트로피도 가속하므로 설계에 매일 투자한다.

어휘

정확히 이 단어를 쓴다. "component", "service", "API", "boundary"로 바꿔 부르지 않는다.

• Module: 인터페이스와 구현을 가진 모든 것. 규모 무관 — 함수, 클래스, 패키지, 계층을 가로지르는 슬라이스. Avoid: unit, component, service.
• Interface: 호출자가 모듈을 올바르게 쓰기 위해 알아야 하는 전부. 타입 시그니처뿐 아니라 불변 조건, 호출 순서, 에러 모드, 필수 설정, 성능 특성, 그리고 암묵 입력·출력(cwd, 환경 변수, ctx에 숨은 값, stdout/stderr, 파일 부수효과). 평가할 때 이 항목을 점검표로 훑는다. Avoid: API, signature(타입 표면만 가리켜 너무 좁다).
• Implementation: 모듈 안쪽의 코드 본체. Adapter와 구분한다 — 작은 adapter에 큰 구현 (Postgres repo)도, 큰 adapter에 작은 구현(in-memory fake)도 있다.
• Depth: 인터페이스에서의 leverage. 호출자(또는 테스트)가 배워야 하는 인터페이스 단위당 쓸 수 있는 동작의 양. 작은 인터페이스 뒤에 많은 동작이면 deep, 인터페이스가 구현만큼 복잡하면 shallow.
• Seam (Michael Feathers): 그 자리를 편집하지 않고 동작을 바꿀 수 있는 장소. 모듈의 인터페이스가 놓이는 위치. 어디에 둘지는 무엇을 뒤에 둘지와 별개의 설계 결정이다. Avoid: boundary(DDD의 bounded context와 겹친다).
• Adapter: seam에서 인터페이스를 만족하는 구체물. 무엇이 들어 있는지가 아니라 어떤 역할(슬롯)을 채우는지를 말한다.
• Leverage: depth가 호출자에게 주는 것. 배운 인터페이스 단위당 더 많은 능력. 구현 하나가 N개 호출 지점과 M개 테스트에서 회수된다.
• Locality: depth가 유지보수자에게 주는 것. 변경, 버그, 지식, 검증이 여러 호출자로 퍼지지 않고 한 곳에 모인다. 한 번 고치면 전부 고쳐진다.

Deep vs shallow

deep:     ┌──────────────┐        shallow:  ┌──────────────────────────┐
          │ 작은 인터페이스 │                  │      큰 인터페이스        │
          ├──────────────┤                  ├──────────────────────────┤
          │              │                  │  얇은 구현(그냥 넘겨줌)     │
          │  깊은 구현     │                  └──────────────────────────┘
          └──────────────┘

인터페이스를 설계할 때 묻는다: 메서드 수를 줄일 수 있나? 파라미터를 단순화할 수 있나? 더 많은 복잡성을 안에 숨길 수 있나?

원칙

• Depth는 구현이 아니라 인터페이스의 속성이다. deep module 안쪽은 작고 교체 가능한 부품으로 구성돼도 된다 — 인터페이스의 일부가 아닐 뿐. 모듈은 외부 seam 외에 자기 테스트가 쓰는 internal seam을 가질 수 있다. 테스트가 쓴다는 이유로 internal seam을 인터페이스로 노출하지 않는다.
• 삭제 테스트. 모듈을 지운다고 상상한다. 복잡성이 사라지면 pass-through였다. 복잡성이 N개 호출자로 다시 나타나면 제 몫을 하던 모듈이다. 판정할 때 운영 호출자 수, 테스트 호출자 수, 사라지는 복잡성, 다른 곳으로 이동하는 복잡성을 따로 적는다 — 이동은 사라짐이 아니다.
• 인터페이스가 테스트 표면이다. 호출자와 테스트는 같은 seam을 건넌다. 인터페이스 너머를 테스트하고 싶다면 모듈 모양이 잘못됐을 가능성이 크다. 먼저 호출자가 관측해야 할 불변식 (실패, 부수효과, 보안상 순서)과 교체 가능한 구현 세부(정확한 argv 배열, 명령 순서)를 가른다 — 전자를 고정하는 테스트는 인터페이스 테스트고 후자를 고정하면 너머를 보는 것이다.
• adapter 하나면 가설적 seam, 둘이면 진짜 seam. 실제로 그 seam을 가로질러 변하는 것이 없으면 seam(포트)을 만들지 않는다. adapter 하나짜리 seam은 그냥 간접화다. adapter는 운영과 테스트를 나눠 종류로 센다; 테스트 adapter가 실제 fault(stale, tamper, 누락)를 나타내면 그 seam은 internal seam으로 인정한다. 같은 역할의 람다 여럿은 하나다.

Testability를 위한 설계

1. 의존성은 받는다, 만들지 않는다. processOrder(order, paymentGateway)는 테스트 가능, 함수 안에서 new StripeGateway()는 어렵다.
2. 결과를 반환한다, 부수효과를 내지 않는다. calculateDiscount(cart) Discount는 테스트 가능, applyDiscount(cart)가 cart.total을 고치면 어렵다.
3. 표면적을 작게. 메서드가 적으면 테스트가 적고, 파라미터가 적으면 setup이 단순하다.