프론트엔드 기술 부채 정리로 코드 가독성과 유지보수성 향상

2026-02-02. 기능은 한 줄도 안 바뀌었는데 하루를 쓴 날이다. 결과물을 PR에 올리면 "이게 뭐가 달라진 거야?"라는 질문이 나올 법한 작업. 그래도 해야 했음.

기술 부채 정리는 자꾸 뒤로 밀린다. 기능 티켓은 눈에 보이고 마감이 있는데, 리팩토링은 당장 아무것도 안 터지니까. 근데 이번에 코드 리뷰를 하다가 _newbmc.scss 파일을 보고 멈췄다. 이름만 봐서는 어디에 쓰이는지 전혀 알 수 없음. 실제로 grep 해보니 실제 참조가 없었다. 죽은 코드였던 거다. 그 파일 하나 때문에 다른 스타일 로직을 파악하는 데 시간을 낭비하고 있었던 셈.

이번 정리 범위

한 번에 다 고치려다 실패한 적이 있어서, 이번엔 연관된 것끼리 묶어서 단계별로 진행했음. 크게 세 영역이었다.

• 뷰 템플릿: 한 파일이 너무 많은 역할을 하고 있었음. 렌더링 책임이 섞여 있어서 특정 UI를 고치려면 관계없어 보이는 부분도 같이 읽어야 했다. 역할 기준으로 분리.
• 스타일시트: 같은 색상 계산이나 여백 규칙이 여러 파일에 흩어져 있었음. 한 곳에서 값을 바꾸면 다른 데가 안 바뀌는 케이스가 생길 수 있는 구조. 중복 통합.
• 프론트엔드 스크립트: 네이밍이 제각각이었음. 어떤 함수는 동사-명사 순, 어떤 건 명사-동사 순. 일관된 컨벤션으로 통일.

각 영역을 별도 커밋으로 나눴다. 커밋 하나에 변경이 집중되어야 나중에 git bisect나 git log로 원인 추적할 때 편하다. 수정 파일 합계 6개, 변경 유형별로 보면 아래처럼 정리됨.

리팩토링할 때 실제로 지키는 것들

이번에도 지켰던 원칙 몇 가지가 있다. 예전에 안 지켜서 고생한 것들이기도 함.

변경 범위는 작게. 한 PR에 모든 걸 때려넣으면 리뷰도 힘들고, 뭔가 깨졌을 때 원인 찾기가 거의 불가능해진다. 기능 테스트를 "이 정도 범위면 여기서 뭔가 잘못됐을 때 바로 찾을 수 있겠다"는 확신이 들 만큼 작게 유지해야 한다.

동작 보증 먼저. 리팩토링 전후로 기존 기능이 그대로 동작하는지 확인하는 게 필수다. 이번엔 변경 후 화면 흐름 전체를 직접 돌려봤음.

의도가 드러나는 이름. _newbmc.scss 같은 이름은 맥락을 알아야만 의미가 통한다. 새로 쓰거나 이름 바꿀 때는 "이 파일/함수/변수가 무엇을 하는지 이름만 보고 알 수 있나?"를 기준으로.

코드로 표현하면 대략 이런 방향이었다.

// 전: 파일명만 봐선 역할 불명
// _newbmc.scss (사실상 dead code)

// 후: 실제로 쓰이는 스타일만, 역할이 드러나는 위치에
// _card-layout.scss, _form-common.scss 등으로 정리

// 전: 일관성 없는 네이밍
function loadUserData() { ... }
function userData_update() { ... }
const user_fetch = () => { ... }

// 후: 동사-명사 컨벤션으로 통일
function loadUserData() { ... }
function updateUserData() { ... }
const fetchUserData = () => { ... }

체감한 것들

기술 부채는 이자가 붙는다는 표현을 자주 쓰는데, 정말 그렇다. 지금 당장은 안 터지지만 기능 추가할 때마다 조금씩 속도가 느려지고, 코드 리뷰 코멘트가 늘어나고, 신규 합류한 사람이 파악하는 데 걸리는 시간이 길어진다. 눈에 잘 안 보이는 비용이라서 무시하기 쉽다.

이번 정리 후 실제로 체감한 변화는 명확했다.

리팩토링이 즉각적인 기능 가치가 없다는 이유로 계속 우선순위에서 밀리면, 어느 순간 새 기능 하나 붙이는 데 비정상적으로 오래 걸리는 구간이 온다. 그때 가서 한꺼번에 고치려면 훨씬 비싸다.

코드는 처음부터 완벽할 수 없다고 생각한다. 요구사항도 바뀌고, 팀의 이해도도 달라지고, 기술 스택도 변한다. 어느 시점에서 최선이었던 구조가 나중엔 짐이 되는 건 자연스러운 일이다. 그게 문제가 아니라, 그걸 방치하는 게 문제인 거임. 주기적으로 다듬는 걸 작업 흐름 안에 집어넣는 게 결국 팀 속도를 유지하는 방법이라고 생각함.