기술 부채 청산으로 코드 가독성과 유지보수성 개선

2026-02-02. 아이콘 변경이랑 충전 알림 URL 추가 작업을 하다가, 손이 간 김에 주변 코드도 같이 정리했음. 기능 변화는 없고 순수하게 내부 구조를 다듬은 날.

기술 부채가 쌓이는 방식

'이 부분 나중에 꼭 정리해야지'라고 생각하면서 그냥 넘어가는 코드가 누구나 있음. 마감이 급했거나, 요구사항이 갑자기 바뀌었거나, 일단 동작하게 만드는 게 우선이었거나. 그 순간에 나쁜 판단을 한 건 아님. 상황이 그랬던 거지.

문제는 그게 반복될 때임. TODO 주석, 어디서 왔는지 불분명한 중복 함수, 역할이 모호하게 섞인 컨트롤러, 맥락 없이 지어진 변수명들이 코드베이스 전반에 조금씩 스며듦. 처음엔 내가 짰으니까 뭐가 어디 있는지 알고 있음. 그런데 3개월 뒤에 돌아보면 낯선 코드가 됨. 내가 짠 코드인데도.

그 상태에서 기능 추가나 버그 수정을 하면, 작업 자체보다 코드를 파악하는 데 시간이 더 걸리기 시작함. 어떤 파일을 건드려야 하는지, 이 로직이 다른 곳에도 중복되어 있는 건 아닌지, 이 변수명이 실제로 무슨 의미인지 - 이걸 파악하는 시간이 곧 부채의 이자임.

이번에 정리한 대상은 세 영역이었음.

• 컨트롤러: 역할이 불명확하게 뒤섞여 있던 부분을 분리
• 서비스 레이어: 여러 곳에 흩어져 있던 중복 로직을 한 곳으로 통합
• 유틸리티: 들쭉날쭉하던 네이밍을 일관된 규칙으로 통일

개별 건수는 많지 않았지만 이런 사소한 것들이 쌓이면 체감 차이가 제법 남.

변경 범위를 어떻게 잡느냐

이게 생각보다 중요함. 한 PR에 네이밍 변경, 파일 구조 재편, 로직 통합을 동시에 때려넣으면 나중에 문제가 생겼을 때 어느 시점에서 터진 건지 특정하기가 어려워짐. diff가 크면 리뷰어 입장에서도 어디를 집중해서 봐야 하는지 모르고, 자연스럽게 흘려보내게 됨.

이번엔 논리적으로 연관된 것들끼리 묶어서 단계별로 진행했음. 각 단계마다 기존 기능이 멀쩡히 동작하는지 확인하면서.

// 1단계: 사용하지 않는 dead code 제거
//        → 기능 변화 없음을 먼저 확인

// 2단계: 공통 로직을 적절한 위치로 이동
//        → 기존 호출부가 동일하게 동작하는지 확인

// 3단계: 의도가 드러나도록 이름 변경
//        → IDE rename 활용, 누락된 참조 없는지 체크

// 4단계: 너무 커진 모듈을 적절한 크기로 분리
//        → import 경로 정리, 순환 참조 없는지 확인

각 단계를 별도 커밋으로 끊어두면 뭔가 잘못됐을 때 어느 지점에서 생긴 문제인지 바로 좁혀짐. 롤백 단위도 작아지고. 이 방식이 한 번에 다 바꾸는 것보다 검증도 쉽고, 나중에 git blame으로 맥락을 추적할 때도 훨씬 읽기가 편함.

이번 변경 규모를 정리하면:

파일 6개를 건드렸는데 각각의 변경이 집중되어 있어서 검증도 크게 어렵지 않았음.

구조가 바뀌면 실제로 뭐가 달라지나

기능은 전혀 바뀌지 않았는데 이후 작업 속도가 실제로 달랐음. 이 부분이 리팩토링의 묘미인데, 동시에 설득이 어려운 이유이기도 함. 효과가 즉각적으로 눈에 보이지 않으니까.

정리 전에는 관련 코드를 찾는 것 자체가 하나의 작업이었음. 비슷한 함수가 두 군데 있으면 어느 쪽을 고쳐야 하는지 확인해야 했고, 한쪽만 수정하고 다른 쪽을 빠뜨리는 버그도 가끔 생겼음. 정리 후에는 수정 포인트가 명확해서 파일을 열자마자 바로 들어갈 수 있었음.

이게 매번 반복되면 누적 효과가 적지 않음. 하루에 비슷한 탐색을 열 번 한다고 하면, 건당 5분에서 1분으로 줄어드는 게 하루 40분 차이임. 기능을 새로 만드는 데 쓰지 못한 40분.

리팩토링을 계속하면서 확실하게 느끼는 건, '완성된 코드'라는 개념이 없다는 거임. 요구사항은 계속 바뀌고, 코드를 짜는 사람의 도메인 이해도도 시간이 지나면서 달라짐. 6개월 전에 완벽하다고 생각했던 구조가 지금은 어색하게 느껴지는 게 이상한 일이 아님. 그러니 주기적으로 다듬는 게 결함이 아니라 자연스러운 과정임.

기술 부채를 미루면 이자가 붙는다는 표현이 비유처럼 들리지만, 코드베이스에서 그 감각이 실제로 느껴짐. 조금씩 자주 정리하는 게 한 번에 큰 리팩토링을 몰아서 하는 것보다 훨씬 안전함. 큰 리팩토링은 검증 비용이 높아서 결국 미루게 되고, 미룬 만큼 더 큰 부채로 돌아옴. 작은 것이 보이면 그때그때 치운다, 가 지금 내 원칙임.