본문으로 건너뛰기

E. 설계할 때 주의할 점

Self-Index의 구현을 살펴보며 정리한 설계상의 주의점입니다. 각 항목은 어떤 문제가 생길 수 있는지와, 다른 프로젝트에 적용할 때 무엇을 기준으로 판단할지를 설명합니다.

실패와 정상 결과를 구분하기​

주의할 점: 오류가 났을 때 빈 결과나 기본값을 반환하면, 호출한 쪽은 작업이 실패한 것인지 정상적으로 결과가 없었던 것인지 구분하기 어렵습니다. 실패한 항목이 집계에서 빠지면 결과가 실제보다 좋아 보일 수도 있습니다.

적용 기준: 계속 진행해도 되는 실패인지 먼저 판단합니다. 계속 진행한다면 실패한 대상, 이유, 건수를 남기고 정상 결과와 구분합니다. 화면에 짧은 오류 요약을 보여 주더라도 원인을 확인할 수 있는 상세 기록은 보존합니다.

관련 주제: 재시도할 오류 구분(D8), 결과 검사(D9).

입력을 보정하기 전에 허용 조건을 정하기​

주의할 점: 잘못된 입력을 자동으로 바꾸면 사용자가 요청한 조건과 실제 실행 조건이 달라질 수 있습니다. 입력을 받는 곳마다 검사 방식이 다르면 같은 값이 어느 경로에서는 통과하고 다른 경로에서는 거부됩니다.

적용 기준: 허용할 값과 중복 여부를 입력을 받는 공통 지점에서 검사합니다. 의미를 바꾸지 않는 정규화와 잘못된 값의 보정을 구분하고, 보정이 필요한 기능이라면 그 규칙과 실제 적용된 값을 알려 줍니다. registry의 이름 중복도 같은 원칙으로 검사합니다.

관련 주제: 실행 전 전체 검증(A4), Registry(B3).

상태의 소유자와 변경 범위를 명확히 하기​

주의할 점: 여러 객체가 같은 상태를 공유하면 한쪽의 변경이 다른 쪽의 동작에 영향을 줍니다. 객체가 불변으로 선언되어 있어도 내부의 list나 dict까지 불변인 것은 아닙니다.

적용 기준: 상태를 누가 보관하고 누가 변경할 수 있는지 정합니다. 객체가 사용할 속성은 초기화 시점에 드러내고, 공유가 필요 없는 값은 객체별로 보관합니다. 읽기 전용으로 전달할 값은 내부 데이터의 변경 가능성까지 확인합니다. lock은 동시 접근을 조율하지만, 서로 다른 실행이 같은 설정을 공유해도 되는지까지 해결해 주지는 않습니다.

관련 주제: Context와 상태 객체(B7), Dataclass(C1), Context manager(C7).

함께 바뀌어야 하는 값은 한곳에서 관리하기​

주의할 점: 같은 정책을 여러 곳에 따로 정의하면 한 곳만 수정했을 때 동작이 달라집니다. 반대로 숫자가 우연히 같다는 이유만으로 하나의 상수로 합치면, 서로 다른 정책을 독립적으로 바꾸기 어려워집니다.

적용 기준: 값이 같은지가 아니라 의미가 같고 함께 변경되어야 하는지를 기준으로 묶습니다. 공통 정책은 한곳에서 정의하고, 서로 다른 제한이나 설정에는 각각의 목적이 드러나는 이름을 붙입니다. 설정에 대응하는 문서도 함께 갱신합니다.

관련 주제: 저장소 문서의 역할 분담(A6).

공개 interface의 사용 조건을 명시하기​

주의할 점: 이름이 명확하고 함수가 짧아도, 어떤 입력을 받고 무엇을 반환하며 언제 실패하는지까지 알 수 있는 것은 아닙니다. 필수 기능과 선택 기능의 구분이 없으면 새 구현을 만드는 사람도 무엇을 구현해야 할지 판단하기 어렵습니다.

적용 기준: 공개 함수에는 입력·반환 타입을 적고, 타입만으로 표현하기 어려운 조건과 실패 동작은 설명합니다. 모든 구현에 필요한 기능과 일부 구현만 지원하는 기능을 구분하고, 같은 역할의 interface는 일관된 방식으로 표현합니다.

관련 주제: ABC와 Protocol(B1), Abstract method(C6).