코드베이스의 구조를 통해 기술 부채를 예방하는 방법
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
웹 개발
대상자
React 앱 개발자, 팀 협업을 위한 코드베이스 설계자, 기술 부채 관리에 관심 있는 개발자
핵심 요약
- 구조가 없는 코드베이스는 기술 부채의 원인이며, PR 검토, 신규 개발자 온보딩, 유지보수에 심각한 장애를 유발
flows/
,services/
,features/
,ui/
,hooks/
폴더 구조를 통해 비즈니스 로직, 서비스, UI, 훅을 명확히 분리하여 코드베이스를 설계- "코드가 스스로 설명해야 한다"는 원칙을 지키면, 테스트, 수정, 확장이 쉽고, 팀 협업 효율성이 극대화됨
섹션별 세부 요약
1. 코드베이스의 구조 부족 문제
- 기술 부채는 명확한 구조 부재에서 비롯되며, PR 검토 지연, 신규 개발자 혼란, 유지보수 어려움으로 이어짐
- "복잡성"은 사실 아키텍처 제약 부재에서 비롯된 것으로, 다음 신호를 통해 확인 가능:
- 컴포넌트가 5가지 이상의 기능을 수행
- 로직 흐름을 머릿속에서 재구성해야 함
- 신규 개발자가 간단한 기능 추가를 위해 며칠 소요
2. 구조 설계의 핵심 원칙
- "다음 단계가 명확해야 한다"는 원칙을 따르면, 개발자는 코드베이스 내에서 빠르게 동작을 추적 가능
- 사용자처럼 앱을 상호작용하고, UI에서 로직, 사이드 이펙트까지 추적해보는 것이 구조 검증 방법
- 모듈성보다는 "유연한 확장성"을 목표로, 컴포넌트가 성장할 때 구조를 명확히 분리해야 함
3. 구조 설계 패턴 및 폴더 구조
flows/
폴더: 비즈니스 로직을 명령형 순서로 모델링 (예:payInvoice.ts
)services/
폴더: 테스트 가능한 유틸리티 로직 (예:formatInvoiceAmount
,canInvoiceBePaid
)features/
폴더: 도메인 또는 화면 단위로 UI, 훅, 테스트를 그룹화 (예:BillingScreen.tsx
)ui/
폴더: 비즈니스 로직을 포함하지 않는 시각적 컴포넌트 (예:BillingCard.tsx
)hooks/
폴더: 훅을 통해flows/
또는services/
와 연결
4. 구조 설계의 장점
- 테스트 용이성:
flows/
와services/
는 테스트 범위가 명확 - 변경 용이성: 구조가 명확하면 수정 시 오류 발생 가능성이 줄어듦
- 신규 개발자 온보딩: 명확한 폴더 구조는 학습 시간을 단축
- 코드베이스의 지속 가능성: "코드가 스스로 설명한다"는 원칙으로, 유지보수 비용을 낮춤
5. 구조 유지의 중요성
- "빠른 수정"은 장기적으로 구조를 약화시킴 (예: 분리된 로직이 UI로 유입)
- 구조의 측정 기준: PR 검토 시간, 신규 개발자 첫 기여 시간, 복잡한 로직이 포함된 핫픽스 수 등
- 구조 부족의 경고 신호: 동일한 모듈이 복잡한 차이점에서 반복적으로 나타남
결론
- "구조를 유지하는 것이 기술 부채를 예방하는 핵심"이며,
flows/
,services/
,features/
등 폴더 구조를 통해 코드베이스를 설계 - "코드가 스스로 설명해야 한다"는 원칙을 실천하면, 팀 협업 효율성 향상과 유지보수 비용 절감 가능
- 구조는 기술 부채가 아닌, 장기적인 코드베이스의 건강을 위한 투자다.