코드 작성 규약
augustinLib/Self-Index의 코드와 설계를 분석하며 얻은 지식과 기존 작성 원칙을 바탕으로 정리한 규약입니다. 원본 코드와 설계의 크레딧은 Self-Index 저자와 기여자에게 있습니다.
프로젝트에 적용할 때의 판단 기준을 설명합니다. Python 문법과 코드는 원칙을 보여 주는 예시이며, 사용 가능한 구현 방식을 제한하는 목록이 아닙니다.
적용 기준
- 변경할 동작과 지켜야 할 계약부터 확인한다. 입력·출력, 오류 처리, 성능 요구, 기존 호출 방식 중 무엇을 유지해야 하는지 파악한 뒤 구현을 선택한다.
- 언어와 프로젝트의 관례에 맞게 적용한다. 같은 목적이라도 언어의 타입 체계, framework의 실행 방식, 기존 공개 API에 따라 적합한 구현이 달라진다.
- 필요한 만큼만 구조를 추가한다. 교체, 재사용, 자원 관리 등 해결할 문제가 있을 때 추상화한다. 규약의 예시에 등장한다는 이유로 class, registry, 설정 파일, 실행 단계를 추가하지 않는다.
- 규칙에는 적용 조건을 함께 고려한다. 예를 들어 "재현성이 필요하면 순서를 고정한다"는 규칙이 모든 collection을 정렬하라는 뜻은 아니다. 원래 순서가 의미 있는 데이터는 그 순서를 보존한다.
함수와 실행 흐름
- 함수는 하나의 명확한 책임을 맡는다. 처리 목적, 변경 이유, 입력·출력 관계를 기준으로 분리한다. 줄 수만 줄이기 위한 분할이나 한 번 쓰는 표현의 불필요한 추상화는 피한다.
- 진입점에서는 전체 흐름이 드러나게 한다. 입력 준비, 검증, 처리, 결과 전달을 구분하되, 단순한 프로그램에 별도의 실행 계획이나 단계 관리 구조를 강제하지 않는다.
- 오류와 예외적인 경우를 먼저 처리해 정상 경로를 읽기 쉽게 한다. guard clause를 사용하되, 정상 흐름을 이해하기 위해 여러 곳을 오가야 할 정도로 분기를 흩어 놓지 않는다.
- 호출 시 인자의 의미가 분명하게 드러나게 한다. 순서를 혼동하기 쉬운 인자는 이름으로 전달하거나 의미 있는 타입으로 구분한다. Python의 keyword-only 인자는 위치를 바꿔 전달하는 실수를 줄이는 한 방법이다.
- 교체나 독립적인 검증이 필요한 의존성은 외부에서 전달받는다. 저장소, 시계, 외부 client 등을 인자로 받을 수 있다. 단순한 내부 객체까지 모두 주입하거나 별도의 DI framework를 도입할 필요는 없다.
- 비용이 큰 작업 전에 확인 가능한 조건을 검증한다. 이후 결과에 따라 결정되는 조건은 필요한 시점에 검사한다. 실행 계획, dry-run, checkpoint는 해당 기능이 필요한 작업에 적용한다.
- 여러 실행 경로의 환경과 계약을 일관되게 유지한다. CLI, API, background 작업이 같은 핵심 로직을 사용하도록 구성한다. 공통 진입점이나 명령 표는 이를 구현하는 선택지다.
모듈과 의존성
- 함께 변경되는 책임은 모으고, 독립적으로 변경되는 책임은 분리한다. 디렉터리 이름이나 파일 수보다 변경이 영향을 주는 범위와 의존 관계를 기준으로 모듈을 나눈다.
- 핵심 로직이 외부 구현의 세부 사항에 불필요하게 의존하지 않게 한다. 외부 형식의 변환은 adapter에서, 실제 구현의 선택과 연결은 조립하는 코드에서 담당할 수 있다.
- 선택 기능의 의존성이 기본 기능의 사용을 막지 않게 한다. 필요하면 lazy import나 기능별 패키지로 분리한다. 항상 필요한 의존성은 일반적인 import를 사용해 오류를 일찍 발견하고 의존 관계를 드러낸다.
- interface와 구현은 읽기와 변경에 도움이 되는 단위로 배치한다. 작은 모듈에서는 함께 둘 수 있고, 여러 구현이 공유하는 계약이 커지면 별도 모듈로 분리한다. 특정 파일 이름을 강제하지 않는다.
- 설정과 고정 데이터는 변경 주체와 사용 범위에 맞게 둔다. 여러 곳이 공유하는 정책은 한곳에서 관리하고, 한 함수에서만 사용하는 값은 사용처 가까이에 둔다.
- 경로의 기준을 명시한다. 배포에 포함된 자원은 package 위치, 사용자 파일은 명시한 입력 경로나 작업 디렉터리 등 용도에 맞는 기준을 사용한다. 우연한 실행 위치나 개발자의 절대 경로에 의존하지 않는다.
이름과 공개 계약
- 이름은 역할과 의미를 설명한다. 도메인에서 통용되는 용어를 사용하고, 임시 실험 이름이나 외부 문서의 번호처럼 맥락 없이는 해석하기 어려운 이름을 피한다.
- 단위를 혼동할 수 있는 값에는 단위를 드러낸다. 이름에 단위를 붙이거나 단위를 표현하는 타입을 쓴다. 예를 들어 시간 값의 단위를 이름과 타입 어디에서도 알 수 없게 두지 않는다.
- 같은 역할에는 일관된 용어를 사용한다. 접미사, boolean 이름, 공개·내부 API 구분은 프로젝트와 언어의 관례를 따른다. 이름에 특정 접두사를 붙이는 것만으로 접근이나 변경이 제한되지는 않는다.
- 공개 함수의 입력·출력 타입을 명시한다. 타입만으로 표현되지 않는 허용 범위, 부작용, 실패 동작도 설명한다. 내부 함수는 복잡도와 프로젝트의 타입 검사 정책에 맞춰 표기한다.
데이터와 상태
- 값의 수명과 변경 가능성에 맞는 표현을 선택한다. 불변 값, 변경되는 상태, 일시적인 결과를 구분한다. Python에서는 dataclass, tuple, dict 등을 사용할 수 있으며 모든 값을 class로 만들 필요는 없다.
- 객체가 유효한 상태로 생성되도록 한다. 필수 불변식은 생성 경로에서 검사한다. dataclass에서는
__post_init__을 사용할 수 있다. 외부 조회처럼 비용이나 실패 가능성이 큰 작업은 생성자에 숨기지 않는다. - 불변성은 내부 데이터까지 확인한다. 필드 재대입을 막아도 그 필드가 참조하는 collection은 변경될 수 있다. 필요한 범위에 맞춰 복사, 읽기 전용 view, 불변 collection을 선택한다. 얕은 복사나 읽기 전용 view가 중첩 객체까지 보호한다고 가정하지 않는다.
- mutable 기본값을 의도치 않게 공유하지 않는다. 객체별 상태는 객체별로 생성한다. 공유 상태라면 누가 소유하고 변경하는지, 언제 초기화되고 정리되는지를 명시한다.
- 객체의 상태와 초기화 과정을 파악할 수 있게 한다. lazy 초기화가 필요하면 미초기화 상태를 명시하고, 실패·재시도·동시 접근 시 동작을 정한다.
- 입력 타입은 언어의 암묵적인 변환까지 고려해 검증한다. 예를 들어 Python에서는 boolean도 정수로 취급되므로, boolean을 허용하지 않는 정수 입력은 별도로 검사한다. 변환 방식은 허용할 타입에 맞춰 선택한다.
Python 메서드와 decorator 선택
호출에 필요한 정보와 사용자가 기대하는 동작을 기준으로 선택한다. 특정 용도에 썼다는 관찰만으로 그 기능의 사용 범위를 제한하지 않는다.
| 선택 | 판단 기준 |
|---|---|
| instance method | 개별 객체의 상태나 동작을 사용한다. |
classmethod | 호출한 class 자체가 필요하다. cls를 통해 class별 설정을 참조하거나 호출한 class의 객체를 생성한다. |
staticmethod | self나 cls가 필요 없지만, class의 책임에 속하며 그 이름 아래에서 제공하는 것이 자연스럽다. 공개 helper에도 사용할 수 있다. |
| 모듈 함수 | 특정 class에 속하지 않는 독립적인 동작이거나 여러 곳에서 공통으로 사용한다. |
property | 사용자가 객체의 속성처럼 읽는 것이 자연스러운 값을 제공한다. 명시적인 작업 실행이 더 적합하면 메서드로 둔다. |
- 상속을 지원하는 classmethod는 호출한 class를 존중한다. 생성이 목적이면 class 이름을 고정하기보다
cls(...)를 사용한다. 하위 class에서도 같은 생성 계약이 성립하는지 확인한다. - 속성 접근에 예상하기 어려운 비용이나 부작용을 숨기지 않는다. property에서 계산이나 lazy load를 수행한다면 비용, 실패 가능성, 캐시 여부가 호출하는 쪽에 드러나야 한다.
- decorator는 반복되는 동작이나 선언을 명확하게 표현할 때 사용한다. 실행 순서, 상태 변경, 등록 같은 효과를 알아보기 어렵게 만드는 중첩은 피한다.
- 캐시는 결과를 재사용해도 되는 조건을 먼저 정한다. 키, 수명, 무효화, 메모리 사용량, 동시 호출 시 중복 계산 가능성을 검토한다. 외부 조회뿐 아니라 계산 결과에도 적용할 수 있다.
- 자원의 획득과 정리를 한 단위로 관리한다. Python의 context manager는 그 구현 방법이다.
단순한 범위 관리에는
@contextmanager, 객체의 여러 동작과 자원 수명이 연결되면 class 구현을 고려한다. 준비 도중 실패한 경우까지 정리 책임을 확인한다.
interface와 확장
- 실제로 교체해야 하는 역할을 기준으로 계약을 정의한다. 공통 호출 형태가 필요하면 함수나 구조적 타입으로 충분할 수 있다. 상속과 기본 구현을 공유할 이유가 있을 때 class 계층을 사용한다.
- 필수 기능과 선택 기능을 구분한다. 필수 동작은 누락을 발견할 수 있게 하고, 선택 동작은 별도 interface, 기능 확인, 명시적인 미지원 오류 중 호출자가 다룰 수 있는 방식으로 표현한다.
- 공통 절차를 강제해야 할 때만 template method를 사용한다. 검증과 정리 순서를 기본 구현에서 보장하고 변경 가능한 동작을 분리할 수 있다. 공개 메서드와 확장 메서드의 이름은 역할에 맞게 정한다.
- 이름으로 구현을 선택해야 할 때 registry를 고려한다. 허용할 대상과 이름, 중복 처리, 등록 시점을 정한다. 여러 항목의 등록이 한 작업이라면 부분적으로 반영된 상태가 남지 않게 한다.
- hook에는 호출 시점과 책임을 명시한다. 기본 동작이 없는 hook도 가능하지만, 정리나 필수 검증을 선택적인 override에만 의존하지 않는다.
- 구현의 차이가 데이터인지 동작인지 구분한다. 값만 다르면 설정으로 표현할 수 있고, 동작이 다르면 함수나 객체로 분리할 수 있다. 작은 값의 차이마다 하위 class를 만들지 않는다.
- 실행할 동작을 전달할 때는 필요한 호출 계약을 정한다. 함수, closure, 호출 가능한 객체 중 상태와 수명에 맞는 것을 선택한다. 상태를 가진다는 이유만으로 불변 dataclass를 강제하지 않는다.
입력 검증과 오류 처리
- 외부 입력과 구성요소 사이의 계약을 경계에서 검증한다. 필요한 값, 타입, 범위, 조합을 확인하고 잘못된 입력은 이유를 밝혀 거부한다. 의미를 보존하는 정규화와 의미가 달라지는 보정을 구분한다.
- 오류는 호출자가 대응할 수 있는 형태로 전달한다. 프로젝트의 예외·오류 타입을 일관되게 사용하고, 원인과 필요한 해결 정보를 보존한다. 예외를 변환할 때도 원인 추적이 가능하게 한다.
- 실패를 정상적인 빈 결과와 구분한다. 실패 후 계속 진행할 수 있다면 누락된 대상과 이유를 기록한다. 아무 결과가 없는 경우와 작업에 실패한 경우를 같은 반환값으로 표현하려면 그 계약을 명확히 한다.
- 재시도는 오류의 일시성과 작업의 반복 실행 가능성을 함께 고려한다. 이미 반영된 쓰기를 다시 실행해도 되는지 확인하고, 필요하면 중복 방지 키나 상태 조회를 사용한다. 횟수와 전체 대기 시간을 제한한다.
- 재시도 책임을 한곳에서 관리한다. SDK와 호출 코드가 중복으로 재시도하지 않도록 조정한다. SDK의 정책이 요구에 맞으면 사용할 수 있으며, HTTP 상태 코드만으로 모든 오류의 재시도 여부를 단정하지 않는다.
- 상태 변경에는 실패 시 복구 방법을 함께 설계한다. transaction, 사전 검증, 임시 결과의 확정, 보상 작업 등 작업의 특성에 맞는 방법을 선택한다. 정리 후에는 원래 실패를 호출자에게 전달한다.
- 취소와 종료 신호를 일반 오류처럼 삼키지 않는다. 언어와 framework가 제공하는 취소 방식을 우선한다.
Python의
BaseException직접 상속이나 포괄적인 처리는 일반 오류 처리 규칙으로 사용하지 않는다. - 다음 단계가 전제로 삼는 결과를 확인한다. 항목의 식별자, 개수, 구조, 값의 유효성을 검증한다. NaN이나 inf가 허용되는지는 해당 데이터와 연산의 계약에 따라 판단한다.
자원과 동시성
- 자원을 획득한 코드의 정리 책임을 명확히 한다. 파일, 연결, lock, 임시 변경은 정상 종료와 예외, 취소 시 모두 정리되게 한다. 전역 상태를 잠시 바꾸는 작업은 다른 실행에 미치는 영향도 고려한다.
- 공유 mutable 상태를 줄이고 필요한 범위만 동기화한다. 실행 환경에 맞춰 lock, queue, transaction, 불변 데이터 등을 선택한다. 단순한 작업에 별도의 read/write lock을 구현하지 않는다.
- client의 동시 사용 가능 여부를 확인한다. 안전하게 공유할 수 있으면 재사용하고, 그렇지 않으면 작업별·thread별 객체나 pool을 사용한다. 생성한 자원이 언제 닫히는지도 정한다.
- lock의 범위와 대기 정책을 정한다. 여러 lock을 획득한다면 순서를 일관되게 유지한다. 즉시 실패, 제한 시간 대기, queue 처리 중 사용자와 호출자가 기대하는 방식으로 동작하게 한다.
- 병렬 실행의 완료 순서와 입력 순서를 구분한다. 결과가 어느 입력에 속하는지 식별할 수 있게 하고, 출력 순서가 계약의 일부라면 이를 복원하거나 보존한다.
- 처리량은 자원 예산과 측정 결과에 맞춰 조절한다. batch와 동시 요청 수에 제한을 두고, 입력이 커져도 메모리와 외부 서비스 한도를 넘지 않게 한다. 최적화 전후의 결과가 같은지도 확인한다.
저장과 재현성
- 저장 방식은 중단 시 요구되는 보장에 맞게 선택한다. 완성된 파일만 보여야 하면 같은 파일 시스템의 임시 파일을 완성한 뒤 교체할 수 있다. append log, database, object storage에는 각 저장 방식의 계약을 따른다. atomic 교체와 전원 장애에도 데이터가 유지되는 보장은 구분한다.
- 기존 데이터를 변경할 때 충돌과 복구를 고려한다. 동시 쓰기를 어떻게 제어하고, 실패 시 어떤 상태가 남는지 정한다. 디렉터리를 여러 번 rename하는 작업 전체가 atomic하다고 가정하지 않는다.
- 경로의 허용 범위가 있는 기능은 실제 접근 대상을 검증한다. 상위 디렉터리 이동과 symlink 등이 허용 범위를 벗어나게 할 수 있는지 확인한다.
- 재개 기능은 이전 결과의 호환성을 확인한다. 저장한 설정, 입력, 코드·형식 version 중 어떤 변경이 재개를 무효화하는지 정한다. 해시 검증은 이를 구현하는 방법이며, 필요한 호환성 정책을 대신하지 않는다.
- 결과를 추적하거나 재현해야 하는 작업은 실행 조건을 남긴다. 코드·의존성 version, 설정, 입력의 식별 정보 등 필요한 정보를 기록한다. 기록에 비밀 값이나 불필요한 원문을 포함하지 않는다.
- 오래 보관하거나 다른 구성요소와 교환하는 데이터는 형식과 호환성 정책을 정한다. 읽을 때 필요한 구조와 값을 검증하고, 지원하지 않는 형식은 명확히 거부한다. 신뢰할 수 없는 데이터의 역직렬화는 제한한다.
- 결정성이 필요한 범위에서 난수와 순서를 제어한다. 독립적인 RNG와 seed, 명시적인 동점 처리 등을 사용할 수 있다. 플랫폼·수치 정밀도·외부 서비스 때문에 같은 seed만으로 결과가 같아지지 않을 수도 있다.
외부 코드와 서비스
- 외부 구현과의 연결은 지원되는 공개 API를 우선한다. 설정, callback, adapter, wrapper 등으로 요구를 충족할 수 있는지 확인한다. 상속은 외부 class가 확장 계약을 제공하고 그 계약을 유지할 수 있을 때 사용한다.
- 외부 구현의 변경이 핵심 로직으로 퍼지지 않게 한다. 내부 API나 patch가 불가피하면 적용 범위, version 조건, 복원 방법을 명시한다. fork가 필요하면 변경 내역과 upstream 갱신 방법을 관리한다.
- 외부 계약에 의존하는 부분을 검증한다. 사용 중인 API, 응답 형식, 기능 지원 여부를 필요한 시점에 확인한다. 내부 구현 전체를 특정 파일 구조나 import 문장에 불필요하게 묶지 않는다.
- 환경에 따라 달라지는 값은 설정으로 분리한다. 설정을 언제 읽고 갱신할지 정하고, 한 작업 안에서 일관된 값을 사용해야 한다면 시작 시점의 설정을 보관한다.
- 외부 응답은 검증한 뒤 사용한다. 생성형 모델의 출력도 같은 원칙을 적용한다. 필요한 구조와 의미를 검사하고, 실패 시 재시도·부분 결과·작업 중단 중 요구에 맞는 정책을 사용한다.
- 요청량, 시간, 비용을 제어한다. timeout, 동시 요청 수, 사용량 제한을 요구에 맞게 설정한다. 요청이나 응답 형식이 다르면 차이가 있는 부분을 분리하고, 공통 코드가 과도한 분기로 복잡해지지 않게 한다.
로그와 사용자 인터페이스
- 로그는 상황을 추적할 수 있는 정보를 담는다. 작업 식별자, 단계, 결과, 실패 원인을 일관되게 기록한다. 출력 형식과 logger는 실행 환경과 기존 도구에 맞춘다.
- 기록의 상세도와 보존 범위를 정한다. 오류 요약과 상세 진단을 구분하고, 로그 크기·민감 정보·운영 비용을 고려한다. 출력 제한으로 정보가 생략되면 그 사실과 상세 내용을 확인할 방법을 알린다.
- 기계가 결과를 소비한다면 안정적인 출력 계약을 제공한다. 사람용 로그를 다시 해석하게 하기보다 필요한 결과와 상태를 구조화해 제공한다. 파일 형식은 소비하는 쪽의 요구에 맞춘다.
- 사용자가 실행 조건과 결과를 이해할 수 있게 한다. 기본값, 설정 우선순위, 허용되는 옵션 조합, 실패 시 동작을 안내한다. CLI의 exit code와 출력 채널은 호출하는 프로그램도 구분할 수 있게 한다.
도구와 검증
- formatter, linter, 타입 검사는 프로젝트의 공통 설정을 따른다. 실제로 유지할 수 있는 규칙을 선택하고, 예외가 필요하면 이유와 범위를 좁게 표시한다.
- 의존성 정책은 배포 형태에 맞춘다. application은 lock 파일 등으로 실행 환경을 재현하고, library는 지원할 version 범위와 호환성을 관리한다. 모든 패키지에 같은 version 고정 방식을 강제하지 않는다.
- 변경한 계약과 실패 가능성에 맞게 검증한다. 정상 동작뿐 아니라 의미 있는 경계 조건, 실패 후 상태, 기존 호출과의 호환성을 확인한다. 검증 범위는 변경의 영향과 비용에 비례하게 정한다.
- 성능을 바꾸는 구현은 정확성과 자원 사용량을 함께 확인한다. 실행 경로나 정밀도가 다르면 비교할 기준과 허용 오차를 정한다.
주석과 문서
- 주석과 문서화 주석의 언어는 프로젝트마다 일관되게 사용한다. 별도 지정이 없으면 코드 주석은 영어를 기본으로 하며, 저장소 문서는 독자에게 맞는 언어로 작성한다.
- 모듈과 공개 API의 목적과 사용 조건을 설명한다. 입력·출력, 부작용, 실패 동작 중 이름과 타입만으로 알기 어려운 내용을 적는다. 언어와 프로젝트가 사용하는 docstring 또는 문서화 형식을 따른다.
- 본문 주석은 의도와 제약을 설명한다. 코드의 동작을 그대로 반복하기보다 순서가 필요한 이유, 유지해야 할 불변식, 외부 시스템의 제약처럼 코드만으로 알기 어려운 내용을 적는다.
- 주석은 현재 동작과 일치하게 유지한다. 세션이나 대화의 이력은 넣지 않는다. 변경 이유의 이력은 commit이나 PR에 남기고, 코드를 이해하는 데 필요한 설계 이유는 주석이나 문서에 기록한다.
- 논리적으로 연결된 코드는 가까이 두고, 다른 단계는 여백으로 구분한다. 모든 단락에 주석을 붙이는 대신 이름·구조·주석이 함께 읽기 쉬운 흐름을 만들게 한다.
- 사용법과 설정이 바뀌면 관련 문서도 갱신한다. 설치, 설정, 확장 방법, 저장 형식 등 독자에게 필요한 내용을 적절한 위치에 두고 같은 정보를 여러 곳에서 다르게 설명하지 않는다.
판단 기준을 적용한 예시
아래 코드는 끝값을 포함하지 않는 정수 구간을 표현한다. 범위는 생성 후 바뀌지 않아 불변 값으로 두고, 구간을 만드는 다른 입력 형식을 classmethod로 제공한다. 길이는 속성으로 읽고, 포함 여부는 인자를 받는 instance method로 계산한다. 각 선택은 이 객체의 역할에 따른 것이며, 모든 class에 같은 구성을 요구하지 않는다.
"""Represent immutable half-open integer intervals."""
from dataclasses import dataclass
from typing import Self
@dataclass(frozen=True)
class Interval:
"""An interval that includes start and excludes end.
Equal bounds represent an empty interval.
Raises ValueError when end is less than start.
"""
start: int
end: int
def __post_init__(self) -> None:
if self.end < self.start:
raise ValueError("end must be greater than or equal to start")
@classmethod
def from_pair(cls, bounds: tuple[int, int]) -> Self:
"""Create an interval from a pair using the calling class."""
return cls(*bounds)
@property
def length(self) -> int:
return self.end - self.start
def contains(self, value: int) -> bool:
return self.start <= value < self.end
같은 범위 계산이 특정 객체의 책임에 속하지 않는다면 모듈 함수로 제공할 수도 있다.
classmethod를 선택한 이유는 생성자라는 이름 때문이 아니라 호출한 class인 cls를 사용하기 때문이다.
이 예시는 타입이 확인된 입력을 전제로 한다. 외부에서 받은 값을 전달하는 프로그램은 그 경계에서 타입과 형식을 검증한다.