기술 부채 정리로 코드 탐색·수정 효율 향상

2026-01-17. 기능은 하나도 안 바뀌는 작업을 하루 동안 했다. 외부에서는 아무것도 달라지지 않았는데, 내부에서는 꽤 많은 게 움직였음.

이번 정리의 출발점은 deprecated 멤버 제거와 sample 관련 파일 삭제였는데, 막상 손을 대기 시작하니 주변에 같이 정리해야 할 게 딸려 나왔다. 코드베이스가 어느 정도 나이를 먹으면 자연스럽게 생기는 현상이다. 처음에는 명확한 이유가 있었던 구조도, 요구사항이 바뀌고 담당자가 바뀌면서 "왜 여기 있는지 모르겠는 코드"가 된다.

뭘 건드렸나

크게 세 레이어를 손봤다.

컨트롤러는 역할이 불명확하게 뭉쳐 있는 부분을 분리했음. 하나의 컨트롤러 안에서 너무 많은 일을 하고 있었는데, 각 메서드가 어느 관심사에 속하는지 따져보면서 쪼갰다. 컨트롤러가 비대해지는 건 초기에는 빠르게 기능 붙이기 좋아서 생기는 문제인데, 나중에 특정 기능만 수정하려고 할 때 전체 파일을 읽어야 하는 상황이 된다.

DB 매퍼는 중복 로직을 통합했다. 비슷한 쿼리 조립 코드가 여러 곳에 흩어져 있었고, 각각 미묘하게 다른 방식으로 처리하고 있었음. 이런 중복은 버그가 한 곳에서 발견됐을 때 나머지 복사본에서도 같은 버그가 있는지 전수 확인해야 해서 피로도가 높다.

뷰 레이어는 네이밍 일관성 문제였다. 같은 개념을 가리키는 변수나 함수명이 파일마다 달랐음. 이건 기능에는 영향이 없지만 코드를 읽는 사람 입장에서는 같은 것인지 다른 것인지 매번 확인해야 해서 인지 부하가 쌓인다.

변경 유형별로 정리하면 이렇다.

어떻게 진행했나

리팩토링에서 제일 많이 실수하는 게 한 번에 너무 넓게 건드리는 거다. 변경 범위가 커지면 검증이 어렵고, 문제가 생겼을 때 어디서 터진 건지 찾기 힘들어진다. 이번엔 논리적으로 연관된 것끼리 묶어서 단계별로 진행했음.

코드 레벨에서 주된 작업은 이 네 가지였다.

// 제거: 사용하지 않는 dead code, deprecated 멤버
// 이동: 공통 로직을 적절한 위치로 재배치
// 이름 변경: 의도가 드러나도록 재명명
// 분리: 너무 큰 모듈을 적절한 크기로 쪼개기

특히 dead code 제거는 생각보다 판단이 까다롭다. "어딘가에서 쓰일 것 같은데" 하는 직감이 자꾸 방해를 하는데, 실제로 참조 추적을 해보면 쓰이지 않는 경우가 대부분이다. 이번엔 참조 없는 코드는 일단 지우는 방향으로 갔고, 지운 후에도 기존 기능 동작은 이상 없었다.

sample 관련 파일은 초기 개발 과정에서 만들어두고 그대로 방치된 것들이었음. 이런 파일들은 코드 탐색할 때 실제 프로덕션 로직인지 예제인지 구분을 모호하게 만든다. 삭제하고 나니 디렉토리 구조가 훨씬 읽기 편해졌다.

기술 부채를 방치하면 실제로 무슨 일이 생기나

"나중에 정리하면 되지"가 쌓이면 어떻게 되는지는 직접 겪어야 실감이 된다. 기능 하나 추가하려고 코드를 열었는데 수정해야 할 포인트를 찾는 데 시간이 더 걸리고, 수정하고 나서도 "혹시 같은 로직이 다른 데도 있지 않나" 하는 불안이 따라온다. 실제로 리뷰하다 보면 같은 버그가 복사된 로직에서 동시에 발견되는 경우가 꽤 있다.

이번 정리 이후 체감한 변화는 이렇다.

기술 부채가 이자처럼 쌓인다는 표현이 있는데, 그게 딱 맞는 말이다. 처음엔 작은 불편이지만 방치하면 복잡성이 기하급수로 늘어나고, 나중에는 새로운 기능을 붙이기 전에 구조부터 이해하는 데 시간을 많이 써야 한다.

코드는 처음부터 완벽하게 짤 수 없다. 그게 당연한 거다. 요구사항이 바뀌고, 초기에 몰랐던 게 시간이 지나면서 드러나고, 팀원이 바뀌면서 맥락이 일부 소실된다. 그래서 주기적으로 다듬는 게 부채를 키우지 않는 현실적인 방법이다. 이번처럼 기능 변경 없이 구조만 건드리는 작업을 일정 주기로 끼워넣는 게 장기적으로는 훨씬 빠른 개발 속도를 만든다.