SQL 주석과 스타일시트 중복 정리로 유지보수성 개선

2026-01-23, 기능 변경 없이 내부 구조만 정리하는 작업을 했다. SQL 쿼리 주석 규칙을 손보고, 스타일시트 중복을 정리하고, 뷰 레이어 네이밍 일관성을 맞췄다. 건드린 파일 총 6개. 배포해도 사용자한테 보이는 변화는 없지만, 코드베이스를 다루는 사람한테는 이런 작업이 쌓이면 나중에 체감이 달라진다.

기술 부채가 쌓이는 방식

기능 추가나 버그 수정을 하다 보면 '나중에 정리해야지' 하고 넘기는 순간들이 있다. 당장 동작하는 게 급하고, 더 중요한 이슈가 기다리고 있다. 그렇게 넘긴 것들이 조용히 쌓인다.

SQL 쪽을 예로 들면, 처음엔 작은 쿼리였던 게 조건이 하나둘 붙으면서 커진다. 누가 왜 이 조건을 붙였는지 코드만으로는 알기 어렵고, 주석도 없거나 처음 짤 때 쓴 짧은 메모 수준에 머물러 있다. 시간이 지나면 그 쿼리를 수정해야 하는 상황이 오는데, 전체 흐름을 다시 파악하는 시간이 작업 시간보다 길어진다.

CSS도 비슷하다. max-width를 예로 들면, 처음엔 컴포넌트마다 로컬하게 선언하는 게 당연하다. 독립적으로 관리하는 게 간단하고 의존성도 없다. 문제는 같은 값을 쓰는 곳이 여러 개 생기면서부터인데, 나중에 값을 수정해야 할 때 어디를 바꿔야 하는지 전부 추적해야 한다. 하나 빠뜨리면 레이아웃이 일부에서만 맞고 다른 데선 틀어지는 상황이 생긴다. 눈에 잘 띄는 페이지에서 생기면 다행이지만, 조용히 깨져있는 채로 한동안 방치되는 경우도 있다.

코드 리뷰나 기능 추가 작업을 하다가 '이 부분 나중에 꼭 정리해야지'라고 생각하는 곳들이 이번에 정리한 것들이었다.

어떻게 정리했나

크게 네 가지 유형으로 나눠서 처리했다.

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

각 유형마다 범위를 좁게 잡고, 변경 후 기능이 그대로인지 확인하면서 단계별로 진행했다. 구조 변경은 기능 변경이 없어야 하는데, 이 둘이 섞이면 뭔가 잘못됐을 때 어디가 문제인지 특정하기가 매우 어려워진다. 이번엔 의도적으로 로직 변경 없이 구조만 손댔다.

CSS max-width 통일은 분산된 선언들을 한 곳에서 관리하도록 정리하는 게 핵심이었다. 값이 동일해도 파일마다 따로 선언되어 있으면 변경 시 전부 찾아야 하고, 하나 빠뜨리는 실수가 생긴다. 중앙에서 관리하면 수정 포인트가 하나로 줄어들고 리뷰할 때도 의도 파악이 빠르다. 단, 이렇게 하면 해당 스타일이 어디서 오는지 파악하기 위해 한 단계 더 타고 들어가야 하는 trade-off가 있다. 중복 제거와 지역성 사이의 균형인데, 이번 케이스는 변경 빈도를 고려했을 때 통합 쪽이 맞다고 봤다.

SQL 주석 정비는 결과적으로 쿼리 자체보다 맥락 문서화 작업에 가까웠다. 각 블록이 어떤 요구사항을 반영하는지, 특정 조건이 왜 들어갔는지를 코드 옆에 남겨두는 것. 다음에 이 쿼리를 보는 사람이 히스토리를 추적하는 시간을 줄여주는 게 목적이다. 지금 당장은 '내가 짠 거니까 알지'라는 생각이 들 수 있는데, 몇 달 뒤에 그 쿼리를 다시 열면 얘기가 달라진다. 주석이 있는 코드와 없는 코드의 독해 속도 차이는 생각보다 크다.

뷰 레이어 네이밍은 같은 개념을 부르는 이름이 파일마다 달랐던 걸 통일했다. item, entry, data 같은 게 섞여 쓰이던 걸 하나로 맞추는 작업. 코드베이스 전체에서 검색어가 여러 개여야 한다는 것 자체가 일관성이 없다는 신호다. 이름 변경은 범위가 크면 실수하기 쉬운 작업이라, 하나씩 확인하면서 처리했다.

리팩토링 이후 체감

기능은 그대로인데 구조가 바뀌면 어떤 효과가 있는지는 당일 바로 체감하기가 어렵다. 오히려 며칠 뒤에 그 파일을 다시 열 때, 또는 관련 기능을 수정해야 할 때 실감한다.

CSS 쪽은 정리 직후에 관련 수정이 생겼는데, 예전이라면 여러 파일을 뒤져야 했을 걸 한 곳에서 처리했다. 작은 사례지만 효과가 눈에 보이는 케이스였다.

리팩토링을 주기적으로 하면서 드는 생각은, 코드는 처음부터 완벽할 수 없다는 거다. 요구사항이 바뀌고, 팀 구성이 달라지고, 이해도가 높아지면서 예전에 짠 방식이 아쉬워 보이는 순간이 계속 온다. 이걸 나쁜 신호로 볼 필요가 없다. 그냥 자연스러운 과정이고, 완성된 코드라는 개념 자체가 없다고 생각한다.

기술 부채를 미루면 이자가 붙는다는 표현이 이번에도 딱 맞았다. 작을 때 치우는 게 나중에 큰 덩어리를 한꺼번에 치우는 것보다 훨씬 낫다. 큰 덩어리가 되면 일정 잡기도 어렵고, 영향 범위도 커서 리스크가 생긴다. 주기적으로 작게 정리하는 게 그래서 의미 있다.

총괄 포지션에서 일하면서 이런 내부 정리 작업을 직접 챙기는 게 쉽지 않은 건 사실이다. 기능 요청이 밀려있고 급한 이슈가 생기면 리팩토링은 자연히 뒤로 밀린다. 그래서 의도적으로 시간을 잡아두지 않으면 '나중에'는 계속 미뤄진다. 이번처럼 명시적으로 정리 작업을 일정에 넣고 처리한 게 앞으로의 유지보수성에 대한 투자라고 생각한다.