하드코딩 상수 추출이 코드 유지보수 비용을 결정짓는 이유와 실무 적용 기준

하드코딩된 값을 상수로 추출하는 가장 큰 이유는 코드의 의도를 명확히 하고 변경에 유연하게 대응하기 위해서입니다. 소스 코드 곳곳에 직접 입력된 숫자나 문자열은 나중에 그 의미를 파악하기 어렵게 만들 뿐만 아니라, 값을 수정해야 할 때 일부를 누락하여 치명적인 런타임 에러를 유발하는 주범이 됩니다.

단순히 '코드가 깔끔해 보인다'는 심미적인 이유를 넘어, 상수를 분리하는 작업은 소프트웨어의 생명 주기 전반에 걸쳐 기술 부채를 줄이는 핵심적인 활동입니다. 특히 대규모 프로젝트일수록 특정 값이 무엇을 의미하는지 추측해야 하는 상황 자체가 개발 효율을 급격히 떨어뜨립니다.

이 과정은 우리가 흔히 말하는 '클린 코드'나 '리팩터링'이라는 상위 주제와 밀접하게 맞닿아 있습니다. 코드의 가독성을 높이는 기초 체력을 기르고 싶다면, 가장 먼저 내 코드 안에 숨어 있는 '매직 넘버'들을 찾아내어 이름을 부여하는 것부터 시작해야 합니다.

많은 개발자가 귀찮다는 이유로 혹은 '나중에 고치면 되겠지'라는 생각으로 하드코딩을 방치하곤 합니다. 하지만 실무에서 이 작은 습관이 어떻게 대형 사고를 막아주는지, 그리고 어떤 기준으로 상수를 관리해야 하는지 구체적으로 살펴보겠습니다.

하드코딩 상수 추출 주제를 읽기 전에 먼저 보면 좋은 대표 이미지 · 핵심 포인트: 왜 필요한지, 언제 추출할지, 장점

핵심 내용 먼저 보기

핵심 키워드 하드코딩 상수 추출 · 연관 검색어 하드코딩 상수 추출, 매직 넘버 제거, 클린코드 리팩터링, 코드 가독성 개선, 자바스크립트 상수 관리

매직 넘버와 매직 스트링이 숨긴 위험성

코드 중간에 갑자기 등장하는 숫자 86400이나 문자열 'PENDING' 같은 값들을 '매직 넘버' 혹은 '매직 스트링'이라고 부릅니다. 작성 당시에는 개발자가 그 의미를 완벽히 이해하고 있겠지만, 한 달 뒤의 본인이나 동료 개발자에게 이 숫자는 아무런 맥락이 없는 정보일 뿐입니다. 86400이 하루를 초 단위로 계산한 값인지, 아니면 특정 서비스의 포트 번호인지 코드를 한참 분석해야 알 수 있다면 이미 가독성 측면에서 실패한 코드입니다.

더 큰 문제는 중복입니다. 같은 값을 여러 군데에서 하드코딩으로 사용하고 있다면, 정책이 바뀌어 그 값을 수정해야 할 때 모든 파일을 뒤져서 하나하나 바꿔야 합니다. 이 과정에서 단 한 곳이라도 수정을 놓치면 시스템은 예측 불가능한 방식으로 동작하게 됩니다. 상수로 추출하면 단 한 곳의 선언부만 수정하면 되므로 변경의 전파를 완벽하게 통제할 수 있습니다.

상수 추출을 결정하는 실무적인 판단 기준

모든 값을 상수로 만들어야 한다는 강박을 가질 필요는 없습니다. 하지만 다음과 같은 경우에는 반드시 추출을 고려해야 합니다. 첫째, 비즈니스 로직에서 의미를 가지는 설정값입니다. 예를 들어 '최대 재시도 횟수', '할인율', '세션 만료 시간' 등은 언제든 변할 수 있고 그 자체로 중요한 의미를 담고 있습니다. 둘째, 두 번 이상 반복되어 사용되는 문자열이나 숫자입니다. 중복은 관리 포인트의 증가를 의미하므로 즉시 상수로 통합하는 것이 좋습니다.

반면, 단순히 UI의 레이아웃을 잡기 위한 일회성 여백 값이나, 수학적 공식에서 변하지 않는 절대적인 상수(예: 원주율) 등은 상황에 따라 해당 함수 내부에서만 지역 변수로 처리하거나 그대로 두는 것이 오히려 코드의 흐름을 방해하지 않을 때도 있습니다. 핵심은 '이 값이 바뀌었을 때 내가 얼마나 고생할 것인가'를 자문해보는 것입니다.

이름 짓기에서 흔히 저지르는 실수와 해결책

상수를 추출할 때 가장 흔히 하는 실수는 값 자체를 이름으로 쓰는 것입니다. 예를 들어 const TEN = 10; 같은 선언은 아무런 의미가 없습니다. 10이라는 숫자가 '페이지당 게시물 수'를 의미한다면 const POSTS_PER_PAGE = 10;이라고 지어야 합니다. 이름은 '값'이 아니라 '역할'을 설명해야 합니다.

또한, 상수의 범위를 너무 넓게 잡는 것도 경계해야 합니다. 모든 상수를 하나의 constants.js 파일에 몰아넣으면 나중에는 수천 줄짜리 거대 파일이 되어 관리가 불가능해집니다. 해당 상수가 특정 도메인이나 컴포넌트에서만 쓰인다면 그 근처에 정의하고, 프로젝트 전반에서 공유되는 설정값들만 공통 관리 파일로 분리하는 전략이 필요합니다.

테스트 코드 작성과 협업 효율의 변화

상수 추출은 테스트 코드를 작성할 때 그 진가를 발휘합니다. 테스트 코드에서 기대값(Expected Value)을 비교할 때 하드코딩된 값을 사용하면, 실제 로직의 상수가 바뀌었을 때 테스트 코드도 일일이 수정해야 합니다. 하지만 공통된 상수를 참조하게 만들면 로직 변경 시 테스트 케이스의 정합성을 훨씬 쉽게 유지할 수 있습니다.

협업 시에도 상수는 강력한 문서 역할을 합니다. 신규 입사자가 코드를 볼 때 변수명만 보고도 시스템의 정책을 파악할 수 있게 해주기 때문입니다. 잘 명명된 상수는 별도의 주석 없이도 코드가 스스로 설명하게 만드는 '자기 설명적 코드(Self-describing code)'의 첫걸음입니다.

결국 하드코딩을 상수로 추출하는 행위는 미래의 나를 포함한 동료 개발자들에 대한 배려입니다. 지금 당장은 1초면 써 내려갈 숫자를 굳이 변수로 선언하는 것이 번거롭게 느껴질 수 있지만, 그 1초의 투자가 나중에 발생할 몇 시간의 디버깅과 수정 작업을 막아줍니다.

이 글을 읽고 난 뒤, 현재 진행 중인 프로젝트의 코드를 다시 한번 살펴보시기 바랍니다. 의미를 알 수 없는 숫자나 반복되는 문자열이 보인다면 지금 바로 적절한 이름을 부여해 상수로 분리해 보세요. 코드가 훨씬 더 명확하게 말을 걸어오는 것을 느낄 수 있을 것입니다.

더 나아가 객체 지향적인 설계나 디자인 패턴을 공부하다 보면, 이러한 상수 관리조차도 설정 파일이나 데이터베이스로 옮겨야 하는 시점을 마주하게 됩니다. 기초적인 상수 추출 습관이 잡혀 있어야 그다음 단계인 유연한 아키텍처 설계로 나아갈 수 있습니다.

자주 묻는 질문

모든 숫자를 다 상수로 빼야 하나요?

아니요. 0이나 1처럼 반복문에서 인덱스로 쓰이거나, 수학적 공식의 일부인 경우 등 의미가 명확하고 변할 가능성이 없는 경우에는 굳이 상수로 추출하지 않아도 됩니다. 비즈니스 로직의 정책을 결정하는 값 위주로 추출하세요.

상수 이름은 대문자로만 써야 하나요?

대부분의 프로그래밍 언어 관례상 전역적으로 사용되는 불변 상수는 'SCREAMING_SNAKE_CASE'(대문자와 언더바)를 사용합니다. 이는 일반 변수와 상수를 시각적으로 즉시 구분하기 위한 약속입니다.

상수 파일이 너무 커지면 어떻게 관리하나요?

도메인별로 분리하는 것이 좋습니다. 예를 들어 API 관련 상수는 apiConstants.js, 사용자 권한 관련은 authConstants.js 식으로 관련 있는 도메인 단위로 묶어서 관리하면 찾기 쉽고 의존성 관리도 편해집니다.

---

해시태그

#하드코딩상수추출 #매직넘버제거 #클린코드리팩터링 #코드가독성개선 #자바스크립트상수관리 #소프트웨어유지보수