[3팀 박준형] Chapter 2-1. 클린코드와 리팩토링

[BBAK-jun]

과제 체크포인트

배포링크

기본과제

• 코드가 Prettier를 통해 일관된 포맷팅이 적용되어 있는가?
• 적절한 줄바꿈과 주석을 사용하여 코드의 논리적 단위를 명확히 구분했는가?
• 변수명과 함수명이 그 역할을 명확히 나타내며, 일관된 네이밍 규칙을 따르는가?
• 매직 넘버와 문자열을 의미 있는 상수로 추출했는가?
• 중복 코드를 제거하고 재사용 가능한 형태로 리팩토링했는가?
• 함수가 단일 책임 원칙을 따르며, 한 가지 작업만 수행하는가?
• 조건문과 반복문이 간결하고 명확한가? 복잡한 조건을 함수로 추출했는가?
• 코드의 배치가 의존성과 실행 흐름에 따라 논리적으로 구성되어 있는가?
• 연관된 코드를 의미 있는 함수나 모듈로 그룹화했는가?
• ES6+ 문법을 활용하여 코드를 더 간결하고 명확하게 작성했는가?
• 전역 상태와 부수 효과(side effects)를 최소화했는가?
• 에러 처리와 예외 상황을 명확히 고려하고 처리했는가?
• 코드 자체가 자기 문서화되어 있어, 주석 없이도 의도를 파악할 수 있는가?
• 비즈니스 로직과 UI 로직이 적절히 분리되어 있는가?
• 코드의 각 부분이 테스트 가능하도록 구조화되어 있는가?
• 성능 개선을 위해 불필요한 연산이나 렌더링을 제거했는가?
• 새로운 기능 추가나 변경이 기존 코드에 미치는 영향을 최소화했는가?
• 코드 리뷰를 통해 다른 개발자들의 피드백을 반영하고 개선했는가?
• (핵심!) 리팩토링 시 기존 기능을 그대로 유지하면서 점진적으로 개선했는가?

심화과제

• 변경한 구조와 코드가 기존의 코드보다 가독성이 높고 이해하기 쉬운가?
• 변경한 구조와 코드가 기존의 코드보다 기능을 수정하거나 확장하기에 용이한가?
• 변경한 구조와 코드가 기존의 코드보다 테스트를 하기에 더 용이한가?
• 변경한 구조와 코드가 기존의 모든 기능은 그대로 유지했는가?
• (핵심!) 변경한 구조와 코드를 새로운 한번에 새로만들지 않고 점진적으로 개선했는가?

---

바닐라 JS → React TypeScript 마이그레이션

커밋 요약 보기

마이그레이션 규모가 커지다 보니 예상했던 커밋 단위를 지키지 못한 부분이 많았습니다.
리뷰하시는 분들의 피로도를 줄이기 위해 커밋 요약을 따로 문서로 정리해두었습니다.
조금이나마 리뷰에 도움이 되었으면 좋겠습니다!

시니어 프론트엔드 개발자 Juno의 피드백

Juno는 Bmad method에서 제공해준 시니어 개발자 + 아키텍터의 페르소나가 입혀진 AI Agent입니다..! 최대한 이번 과제를 일관성 있게 진행하도록 하기위해 Juno와 함께 과제를 진행했으며, 클린코드가 무엇인지 제가 지양하는 바에대해서 자주 전달했습니다.

변경 사항

아키텍처 개선

• 바닐라 JS에서 React TypeScript로 전환
• MVVM 패턴 도입으로 비즈니스 로직과 UI 분리
• 타입 안전성 확보

주요 리팩토링

// Before: 전역 상태 + DOM 조작
cartState.updateQuantity(productId, quantity);
document.querySelector('.cart-total').textContent = total;

// After: ViewModel + React
const { updateQuantity, cartSummary } = useCartViewModel();
updateQuantity(productId, quantity);

구조 변경

src/
├── components/         # UI 컴포넌트
├── viewmodels/        # 비즈니스 로직
├── types/             # 타입 정의
└── context/           # 상태 관리

핵심 개선점

1. 상태 관리 체계화

// CartViewModel.ts - 장바구니 로직 분리
export const useCartViewModel = () => {
  const [state, dispatch] = useReducer(cartReducer, initialState);
  
  const addToCart = (product: Product, quantity: number) => {
    if (quantity > product.stock) {
      throw new Error('재고 부족');
    }
    dispatch(cartActions.addToCart(product, quantity));
  };

  return { cartItems: state.items, addToCart };
};

2. 타입 안전성

interface CartItem {
  product: Product;
  quantity: number;
  subtotal: number;
}

interface CartState {
  items: CartItem[];
  totalPrice: number;
}

3. 컴포넌트 단순화

// CartItem.tsx - 순수 UI 컴포넌트
const CartItem: React.FC<CartItemProps> = ({ item, onUpdateQuantity }) => {
  return (
    <div className="cart-item">
      <ProductInfo product={item.product} />
      <QuantityControl onQuantityChange={onUpdateQuantity} />
    </div>
  );
};

테스트 개선

Before

• DOM 조작 테스트 위주
• 통합 테스트만 가능

After

• ViewModel 단위 테스트 가능
• 컴포넌트 격리 테스트
• 타입 체크로 런타임 에러 감소

성능 최적화

• 불필요한 DOM 조작 제거
• React의 효율적인 렌더링 활용
• 메모이제이션을 통한 재계산 방지

유지보수성 향상

• 관심사 분리로 코드 이해도 증가
• 타입 시스템으로 리팩토링 안전성 확보
• 컴포넌트 재사용성 증가

마이그레이션 방식

점진적 마이그레이션으로 기존 기능 유지:

1. 타입 정의 먼저 생성
2. ViewModel 계층 구현
3. React 컴포넌트로 단계별 전환
4. 기존 로직 제거

과제 셀프회고

과제를 하면서 내가 제일 신경 쓴 부분은 무엇인가요?

MVVM 아키텍처 도입과 페르소나 기반 시나리오 설계에 가장 많은 시간과 신경을 썼습니다.
클린 아키텍처 원칙을 적용하고, View와 상태 간의 결합을 최소화하려고 했습니다.

MVVM 패턴 적용에서 배운 점

이전에 MVVM 디자인 패턴이란을 작성하면서 React 환경에서 MVVM 패턴의 이론적 배경을 정리했었는데, 이번 프로젝트를 통해 실제 바닐라 JS → React TypeScript 마이그레이션에서 MVVM 패턴을 적용해보며 다음과 같은 새로운 인사이트를 얻었습니다:

이전 글에서 다룬 내용:

• ViewModel과 View의 1:N 관계
• 컴포넌트 구현부와 리턴부의 관계 분리
• 단방향 데이터 바인딩의 이해

이번 프로젝트에서 새롭게 알게된 점:

1. 점진적 마이그레이션에서 MVVM 적용의 실용성: 기존 바닐라 JS의 전역 상태와 DOM 조작 코드를 React의 ViewModel로 점진적으로 전환할 때, 기존 로직을 유지하면서 새로운 패턴을 도입하는 구체적인 방법론
2. useReducer와 MVVM의 궁합: 이전에는 useState 중심으로 생각했는데, useReducer가 ViewModel에서 복잡한 상태 관리에 더 적합함을 실제로 경험
3. Context와 ViewModel의 결합: 전역 상태 관리에서 Context Provider와 ViewModel의 조합이 어떻게 작동하는지 실제 구현을 통해 체험
4. 타입 시스템과 MVVM: TypeScript 환경에서 Model, View, ViewModel 각 계층의 타입 안전성을 보장하는 구체적인 방법들

실제 적용에서 느낀 MVVM의 장점:

• 바닐라 JS의 명령형 DOM 조작을 선언적 UI로 자연스럽게 전환
• 비즈니스 로직과 UI 로직의 명확한 분리로 테스트 용이성 증가
• 기존 기능을 유지하면서 점진적 개선이 가능한 구조적 안정성

추가된 내용

BMAD Method 관련 링크

• BMAD Method 사용 경험기 - 페르소나 기반 협업 경험 상세 기록

프로젝트 관리 링크

• Brownfield 아키텍처 - 레거시 시스템 개선 전략

과제를 다시 해보면 더 잘 할 수 있었겠다 아쉬운 점이 있다면 무엇인가요?

MVVM 패턴 적용과 페르소나 협업을 더 체계적으로 진행했으면 좋았을 것 같습니다.

리뷰 받고 싶은 내용이나 궁금한 것에 대한 질문 편하게 남겨주세요 :)

1. MVVM 패턴 적용에 대한 방향성 피드백 요청

MVVM 패턴을 적용할 때 ViewModel의 관여 범위에 대해 고민이 많았습니다. ViewModel이 View의 상태를 외부 세계와 연결해주는 계층이라 정의하고 작업했는데, 이 정의와 역할 분리가 적절했는지 궁금합니다.
특히, React + TypeScript 환경에서 MVVM 패턴이 적합한 선택인지, 아니면 다른 아키텍처 패턴(e.g., MVI, MVC, Clean Architecture)이 더 나았을지도 알고 싶습니다.

2. 페르소나 기반 협업 전략 피드백 요청

현재 3개의 페르소나(예: 일반 사용자, 관리자, 비로그인 사용자)를 기반으로 기능 시나리오를 구체화했는데, 이 조합이 협업과 사용자 중심 기능 정의에 충분했는지 피드백 받고 싶습니다.
**다른 페르소나(예: QA, CS팀, 장애 대응 담당자 등)**를 고려하는 것이 향후 협업이나 기능 설계에 더 유리했을지도 궁금합니다.

3. 마이그레이션 시점과 전략 피드백 요청

바닐라 JS에서 React + TypeScript로 마이그레이션할 때 MVVM 패턴을 함께 도입했는데,
아키텍처 도입 시점이 적절했는지, 더 작은 단위에서 점진적으로 도입했어야 했는지 판단이 어렵습니다.
실제로 View와 ViewModel을 처음부터 분리하면서 진입장벽이 높아졌다는 느낌도 있었는데, 이에 대한 피드백을 듣고 싶습니다.

4. 테스트 전략 및 ViewModel 단위 테스트 관련

ViewModel 단위 테스트를 일정 비율 이상 작성했는데,
이 비중(예: ViewModel 기준 80% 이상 테스트 작성)이 현실적인 테스트 전략인지, 혹은 ViewModel의 역할을 더 축소하거나 확장함으로써 더 나은 테스트 전략이 있었는지도 궁금합니다.

5. 성능 최적화 및 상태 관리 전략

ViewModel 내부에서는 상태 관리를 위해 Context + useReducer 조합을 사용했습니다.
이 구조가 성능 측면에서 적절했는지, 혹은 Recoil, Zustand, Valtio 등 더 나은 상태 관리 대안이 있었는지도 궁금합니다.
특히, Context+Reducer 기반의 리렌더링 구조가 MVVM에서 자연스러운 선택인지, View와의 결합도 관점에서 개선할 수 있는 여지가 있는지도 피드백 받고 싶습니다.

6. 확장성과 유지보수 관점에서의 구조 피드백

현재 구현한 MVVM 구조가 향후 기능 확장(예: 페르소나 추가, 멀티뷰 대응, 서버 API 변경 등)에 얼마나 유연할지 확신이 없습니다.
ViewModel이 가진 역할의 적절성과 도메인 계층을 분리하지 않은 점이 장기적인 유지보수에 어떤 영향을 줄 수 있는지 의견이 궁금합니다.

7. 추상화 레벨

평탄화되어있는 폴더구조로인해 관심사의 레벨이 올바르게 정렬되어있지 못한 구조로 보입니다.
FSD말고 평탄화되어있는 폴더구조를 개선할수있는 방법이 있을까요?

[k-sang-soo]

준형님이 공유해주신 덕분에 저도 클로드 코드에 BMAD와 Super Claude를 조합해서 사용해봤습니다!
아주 기초적인 수준에서 써본 거지만 확실히 그냥 사용할 때 보다 퀄리티가 좋더라구요 감사합니다!

[BangDori]

@BBAK-jun

안녕하세요, 준형님!
이번 과제에서 PR과 코드들을 살펴보면서 정말 많은 걸 배울 수 있었습니다. 감사합니다 🙇🏻‍♂️

리팩토링 과정에서 준형님이 MVVM 패턴을 어떻게 적용하셨는지를 보면서 흥미로운 점이 많았고, 궁금한 부분도 생겨 이렇게 질문드리게 되었습니다!

이전에 MVVM 디자인 패턴이란을 작성하면서 React 환경에서 MVVM 패턴의 이론적 배경을 정리했었는데, 이번 프로젝트를 통해 실제 바닐라 JS → React TypeScript 마이그레이션에서 MVVM 패턴을 적용해보며 다음과 같은 새로운 인사이트를 얻었습니다:

제가 이해하기로는 React의 핵심은 단방향 데이터 흐름이고, MVVM 패턴은 양방향 바인딩이라는 특성이 있어서 본질적으로는 충돌하는 부분이 있다고 생각해요. 그래서 React와 MVVM은 서로 섞이기 어려운 개념이라고만 생각하고 있었는데, 이번 과제에서 MVVM을 적용하신 이유가

1️⃣ React의 단방향 데이터 흐름을 더 잘 이해하기 위해서인지, 아니면 다른 특정 목적이 있어서 적용하신 건지 궁금합니다!

useReducer와 MVVM의 궁합: 이전에는 useState 중심으로 생각했는데, useReducer가 ViewModel에서 복잡한 상태 관리에 더 적합함을 실제로 경험

이 부분을 읽고 제가 이해한 바가 맞는지 여쭤보고 싶어요.

2️⃣ useState와 달리 useReducer는 View 입장에서 추상화된 ViewModel을 구독하고, 특정 액션을 dispatch하면 내부적으로 상태가 갱신되고 그게 자동으로 View에 반영되니까, 복잡한 상태 관리에 더 적합하다고 이해했는데요, 이렇게 이해해도 될까요?

packages(eslint, prettier), pnpm-workspace.yml 정의

제가 모노레포를 한 번도 다뤄본 경험이 없어서, 이렇게 설정을 해두신 걸 보고 '와 대박 맛있다'라는 생각을 했는데요. ㅋㅋ

3️⃣ 이렇게 구성하신 이유가 혹시 모노레포 스타일을 적용하신 건가요? (제가 모노레포는 처음 접해봐서, 어떤 장점이나 의도가 있었는지 궁금합니다.)

[BBAK-jun]

@BangDori

네 안녕하세요 병준님

1. 제가 생각하는 MVVM은 양방향 데이터흐름을 지원할수도 있지만 단방향데이터흐름을 지원하는데에도 문제가없습니다.
   view는 viewModel을 구독하기만 하는 형태고
   viewModel은 여러 스토어를 구독하여 view에게 필요한 데이터를 전달하는 중간 매개층 형태라고만 봐주시면 좋을것같습니다.

2. 제가 useState와 useReducer를 사용하는 기준은 조금더 고수준의 상태를 다룰떄에는 useReducer라고 보시면 될것같습니다. 지금 보시는것과 같이 꽤나 큰 도메인 엔티티를 다루고있습니다. 이를 useState로 잘게 쪼갤수도있겠지만, 액션 기반으로 상태를 변경하는데에는 dispatch와 액션 핸들러로 트리깅시키면 도움이되지않을까 싶어서 사용했습니다.

export interface ProductState {
  products: Product[];
  filteredProducts: Product[];
  selectedCategory: string | null;
  searchTerm: string;
  sortBy: 'name' | 'price' | 'stock' | null;
  sortOrder: 'asc' | 'desc';
}

3. 모노레포로 구성을 변경한이유는 단순히 제가 편하기 위함이었습니다.

저는 주로 pnpm dev를 사용해서 개발환경을 키곤하는데 하나의 패키지에서 3개의 웹애플리케이션을 다루다보니 html부터 js 엔트리포인트까지 논리적인 단위로 분리가되다보니 은근 불편하더라고요
그래서 워크스페이스를 구성하여 각각의 패키지로 분리했습니다.
그리고 이를 분리하니 eslint설정을 각각 패키지에 맞게 구성할수있었다는 장점이 있었습니다...!

• origin : 아무런 설정이 없음(브라운 필드)
• basic : JS 린트설정이 필요함(그린필드)
• advanced : JS + react + typescript 린트설정이 필요함(그린필드)

결론은 단순히 저의 경험을 향상시키기위해 빠르게 재구성한것밖에없었습니다 ㅎㅎ

[BangDori]

어머나 빠른 답변 너무 감사합니다 ㅋㅋㅎㅎㅋㅎㅋ

MVVM 패턴에 대해서 크게 생각해본 적이 없었는데, 준형님이 작성해주신 글과 PR을 보면서 저도 MVVM 패턴에 대해 다시금 상기하게 됐고 또 새로운 점들도 많이 알게 된 것 같아요. (모노레포 구조, 브라운 필드, 그린 필드 용어.. 까지 ㅋㅋ)

친절하게 답변해주셔서 넘넘 감사합니다 ㅎㅎㅎ