개발 생산성 30% 높인 마법의 숫자 제거 경험: PM/기획자가 알아야 할 코드 품질 개선

PM/기획자도 알아야 할 마법의 숫자/문자열 안티패턴이 비즈니스에 미치는 악영향과 코드 품질 개선으로 개발 생산성을 높이는 실무 경험을 공유합니다.

개발 생산성 30% 높인 마법의 숫자 제거 경험: PM/기획자가 알아야 할 코드 품질 개선

안녕하세요, 여러분. 기획자나 PM으로 일하면서 이런 경험 있지 않으신가요? 개발자와 이야기하다가 "이거 상수로 빼야 할 것 같은데요?" "여기 하드코딩된 값은 어디서 나온 거죠?" 같은 알 수 없는 용어들이 튀어나오는 순간 말이죠. 혹은 특정 기능의 로직을 이해하려고 문서를 보거나 개발자 설명을 들을 때, 뜬금없는 숫자나 문자열이 튀어나와 고개를 갸웃했던 경험이 있을 겁니다. 예를 들어, "만료일은 `7`일로 할게요"라거나, "주문 상태 `1`은 결제 완료, `2`는 배송 중이에요"와 같은 식이죠.

이런 숫자나 문자열들은 겉보기에는 아무 문제가 없어 보이지만, 사실은 우리 코드와 비즈니스 로직을 망가뜨리는 '마법의 숫자(Magic Number)' 또는 '마법의 문자열(Magic String)'이라는 안티패턴의 주범입니다. 개발자만의 문제가 아닙니다. 이런 안티패턴은 결국 버그를 유발하고, 기능 개선 속도를 늦추며, 궁극적으로는 우리 팀의 개발 생산성을 떨어뜨리는 주범이 됩니다. 실제로 저희 팀은 이런 마법의 숫자/문자열을 제거하는 작업을 진행한 후, 개발 생산성이 약 30% 이상 향상되는 놀라운 경험을 했습니다.

이번 글에서는 기획자/PM의 관점에서 이 '마법의 숫자/문자열'이 무엇이며, 왜 문제이고, 어떻게 우리가 이 문제를 해결하는 데 기여할 수 있는지 실무 경험을 바탕으로 이야기해보려 합니다.

📑 목차

• 우리가 모르는 사이 코드를 망치는 '마법의 숫자/문자열'의 정체
• PM/기획자에게 '마법의 숫자/문자열'이 치명적인 이유
• PM/기획자가 직접 확인할 수 있는 '마법의 숫자/문자열' 체크리스트
• [체크리스트 1] 특정 숫자/문자열의 의미가 모호한가?
• [체크리스트 2] 동일한 값인데 여러 곳에 흩어져 사용되는가?
• [체크리스트 3] 조건문이나 반복문에 갑자기 나타나는 정체불명의 숫자/문자열?
• '마법의 숫자/문자열'이 비즈니스에 미치는 실제 영향
• PM/기획자가 '마법의 숫자/문자열' 문제를 해결하는 데 기여하는 방법
• 1. 명확한 요구사항 정의 및 상수화 대상 발굴
• 2. 개발자와의 긴밀한 소통 및 질문
• 3. 문서화의 중요성 강조 및 참여
• 4. '코드 품질'을 비즈니스 우선순위로 인식
• '마법의 숫자/문자열' 제거 후 얻은 놀라운 변화와 성과
• 마무리하며: 코드 품질은 곧 비즈니스 품질

Image by Peggy_Marco on Pixabay

우리가 모르는 사이 코드를 망치는 '마법의 숫자/문자열'의 정체

마법의 숫자/문자열은 코드 안에 갑자기 나타나지만, 그 의미를 명확히 설명하는 이름이 없는 숫자나 문자열을 말합니다. 마치 마법처럼 코드 안에 뿅 하고 나타나지만, 개발자 본인조차 시간이 지나면 그 의미를 잊어버리거나 다른 개발자가 코드를 이해하기 어렵게 만듭니다.

예를 들어볼까요?

// 상품 가격에 10% 할인을 적용하는 코드 (마법의 숫자 사용)
discountedPrice = originalPrice * 0.9; 

여기서 `0.9`는 무엇을 의미할까요? 10% 할인이라는 것을 유추할 수는 있지만, 코드 자체만으로는 알 수 없습니다. 만약 할인율이 바뀐다면? 코드를 만든 개발자가 아니면 이 `0.9`가 할인율이라는 것을 바로 알기 어렵습니다.

반면, 다음과 같이 코드를 작성하면 어떨까요?

// 상수로 명확히 정의된 할인율을 사용하는 코드
const DISCOUNT_RATE_TEN_PERCENT = 0.9;
discountedPrice = originalPrice * DISCOUNT_RATE_TEN_PERCENT;

이제 `DISCOUNT_RATE_TEN_PERCENT`라는 이름만으로도 `0.9`가 10% 할인율을 의미한다는 것을 명확히 알 수 있습니다. 이처럼 특정 값에 명확한 이름을 부여하는 것을 상수화(Constantization)라고 합니다.

PM/기획자에게 '마법의 숫자/문자열'이 치명적인 이유

개발자만의 문제처럼 보이지만, 사실 기획자/PM에게도 치명적입니다. 왜냐하면:

• 요구사항 변경 시 높은 비용: 할인율을 10%에서 20%로 바꾸려면, 개발자는 코드 곳곳에 숨어있는 `0.9`를 찾아 `0.8`로 일일이 바꿔야 합니다. 이 과정에서 실수가 발생하면 치명적인 버그로 이어집니다.
• 잦은 버그 발생: 의미가 불분명한 값은 개발자의 오해를 불러일으켜 잘못된 로직 구현으로 이어질 가능성이 높습니다. "주문 상태 `1`은 결제 완료인가, 결제 대기인가?" 와 같은 혼란이 발생할 수 있습니다.
• 기능 개발 속도 저하: 개발자가 코드를 이해하고 변경하는 데 더 많은 시간을 소모하게 되어, 새로운 기능을 만들거나 기존 기능을 개선하는 속도가 느려집니다.
• 팀 간 의사소통 비효율: 기획-개발-디자인 팀 간에 특정 숫자나 문자열의 의미를 두고 계속해서 질문하고 확인해야 하는 상황이 발생합니다.

PM/기획자가 직접 확인할 수 있는 '마법의 숫자/문자열' 체크리스트

이제 여러분이 실무에서 '마법의 숫자/문자열'을 발견하고 문제 제기를 할 수 있도록 간단한 체크리스트를 공유합니다. 개발 지식이 깊지 않아도 충분히 적용할 수 있는 관점입니다.

[체크리스트 1] 특정 숫자/문자열의 의미가 모호한가?

개발자가 설명하는 로직이나 문서에서 특정 숫자나 문자열이 나타났을 때, 그 값의 정확한 의미를 바로 파악하기 어렵다면 의심해 보세요.

• 예시 상황: "이벤트 기간은 `7`일로 고정이고, 상품 상태 `A`는 판매 중을 의미합니다."
• 점검 질문: 왜 하필 `7`일인가요? `A`는 무슨 약자인가요? 다른 상태는 없나요?
• 문제점: `7`이 '일주일'을 의미하는지, '이벤트 유지 기간'을 의미하는지 명확하지 않습니다. `A` 역시 다른 상태와의 구별이 어렵고, 나중에 `B`, `C` 상태가 추가될 때 혼란을 야기할 수 있습니다.
• 해결책: `EVENT_DURATION_DAYS = 7`, `PRODUCT_STATUS_SELLING = "A"`처럼 이름을 부여해야 합니다.

[체크리스트 2] 동일한 값인데 여러 곳에 흩어져 사용되는가?

특정 숫자나 문자열이 여러 기능이나 로직에 걸쳐 동일하게 사용되는데, 각각 독립적으로 기재되어 있다면 이는 잠재적인 문제입니다.

• 예시 상황: 회원 가입 시 기본 포인트 지급 (`1000`점), 특정 이벤트 참여 시 추가 포인트 지급 (`1000`점), 친구 추천 시 추천인에게 포인트 지급 (`1000`점).
• 점검 질문: 이 `1000`이라는 숫자가 모두 같은 의미인가요? 나중에 이 기본 지급 포인트를 변경하려면 어떻게 해야 하나요?
• 문제점: 만약 기본 지급 포인트를 `1000`점에서 `2000`점으로 변경해야 한다면, 개발자는 코드를 뒤져 `1000`을 찾아 `2000`으로 바꿔야 합니다. 이 과정에서 하나라도 놓치면 버그가 발생하고, 포인트 지급 로직이 뒤죽박죽이 될 수 있습니다.
• 해결책: `DEFAULT_SIGNUP_POINT = 1000`처럼 한곳에 정의하고 여러 곳에서 이 상수를 참조하게 해야 합니다.

[체크리스트 3] 조건문이나 반복문에 갑자기 나타나는 정체불명의 숫자/문자열?

개발자가 설명하는 로직 중 "만약 에러 코드가 `401`이면 로그아웃 처리하고", "리스트를 `5`개까지만 보여줍니다" 와 같이 조건이나 반복문의 기준이 되는 숫자/문자열에 대한 설명이 부족하다면 주의하세요.

• 예시 상황: "사용자 권한이 `3`이면 관리자 기능에 접근 가능하고, 게시글은 최대 `10`개까지 표시됩니다."
• 점검 질문: 왜 `3`이 관리자 권한인가요? 다른 권한은 없나요? 왜 `10`개까지인가요? 나중에 `15`개로 바꾸려면 어떻게 되나요?
• 문제점: `3`이라는 숫자가 어떤 사용자 권한을 의미하는지 불분명하며, `10`이라는 숫자도 명확한 이유 없이 하드코딩된 값일 가능성이 높습니다. 이러한 값들은 변경 시 오류를 유발하고, 코드의 유연성을 떨어뜨립니다.
• 해결책: `USER_ROLE_ADMIN = 3`, `MAX_POST_COUNT_PER_PAGE = 10`과 같이 명확한 상수로 정의해야 합니다.

'마법의 숫자/문자열'이 비즈니스에 미치는 실제 영향

'마법의 숫자/문자열'을 방치하면 단순한 개발의 불편함을 넘어, 비즈니스에 직접적인 손실을 가져옵니다. 저희 팀의 경험을 바탕으로, 상수화 작업을 통해 얼마나 큰 변화를 가져왔는지 비교해 보겠습니다.

영향 항목	마법의 숫자/문자열 사용 시 (이전)	상수화 적용 후 (이후)	개선 효과 (측정치)
기능 변경 소요 시간	평균 3일 (숨겨진 값을 찾아 변경하고 테스트)	평균 1일 (정의된 상수만 변경하고 테스트)	약 67% 시간 단축
유지보수 비용	잦은 버그 발생으로 인한 추가 공수 발생, 운영 비용 증가	버그 감소로 안정적인 서비스 운영, 운영 비용 절감	버그 관련 공수 50% 감소
신규 기능 개발 속도	기존 코드 이해에 시간 소모, 복잡성으로 인한 개발 지연	코드 이해 용이, 재사용성 증가로 개발 속도 향상	기능 출시 기간 20% 단축
팀 간 커뮤니케이션	모호한 용어 사용, 빈번한 의미 재확인	명확한 용어 정의, 효율적인 의사소통	불필요한 논의 시간 40% 감소

위 표에서 볼 수 있듯이, 마법의 숫자/문자열 제거는 단순히 코드를 깔끔하게 만드는 것을 넘어, 실질적인 개발 생산성과 비즈니스 효율성을 크게 향상시킵니다. 저희 팀은 이 작업을 통해 버그 수정에 낭비되던 리소스를 신규 기능 개발에 집중할 수 있었고, 결과적으로 더 빠르게 시장에 제품을 출시할 수 있었습니다.

Image by Hans on Pixabay

PM/기획자가 '마법의 숫자/문자열' 문제를 해결하는 데 기여하는 방법

그렇다면 PM/기획자인 우리는 이 문제에 어떻게 기여할 수 있을까요? 코드를 직접 수정할 수는 없지만, 우리의 역할은 매우 중요합니다.

1. 명확한 요구사항 정의 및 상수화 대상 발굴

기능을 기획할 때부터 변동 가능성이 있거나 의미가 명확해야 하는 숫자/문자열에 대해 명확한 이름을 부여하는 습관을 들여야 합니다. 예를 들어 "최대 첨부 파일 개수는 5개"라고 할 때, 단순히 `5`가 아니라 `MAX_ATTACHMENT_COUNT = 5`와 같이 개발자가 상수로 정의할 수 있도록 유도하는 것이죠. 이러한 값들을 요구사항 정의서나 기능 명세서에 명시하는 것만으로도 큰 도움이 됩니다.

2. 개발자와의 긴밀한 소통 및 질문

개발자가 설명하는 로직이나 작성된 코드(만약 볼 수 있다면)에서 의미가 모호한 숫자나 문자열을 발견하면 주저하지 말고 질문하세요. "이 `3`이라는 숫자는 무엇을 의미하나요?", "이 `admin`이라는 문자열은 고정 값인가요, 아니면 변경될 수 있는 값인가요?"와 같이 질문하고, 가능하면 명확한 이름을 제안해 보세요. 개발자도 자신의 코드를 다시 한번 돌아보는 계기가 될 수 있습니다.

3. 문서화의 중요성 강조 및 참여

API 문서, 기능 명세서, 정책 문서 등 모든 문서에 상수로 관리되어야 할 값들의 의미와 용도를 명확히 기재하도록 개발팀에 요청하고, 함께 참여하세요. 문서가 잘 되어 있으면 새로운 팀원이 합류했을 때 빠르게 업무에 적응할 수 있고, 불필요한 질문을 줄일 수 있습니다. 이는 결국 팀 전체의 생산성으로 이어집니다.

4. '코드 품질'을 비즈니스 우선순위로 인식

때로는 개발팀에서 "이 부분은 상수화가 필요하다"고 이야기해도, 당장의 기능 개발에 밀려 후순위가 되는 경우가 많습니다. 이때 PM/기획자가 나서서 코드 품질 향상이 장기적인 비즈니스 가치와 직결됨을 인식하고, 개발팀의 노력을 지지하며 우선순위를 부여하는 역할을 해야 합니다. 이는 단순한 기술 부채 해결이 아니라, 미래의 개발 속도와 서비스 안정성을 위한 투자임을 강조하는 것이 중요합니다.

Image by 422737 on Pixabay

'마법의 숫자/문자열' 제거 후 얻은 놀라운 변화와 성과

저희 팀은 몇 년 전 대대적으로 코드 내 마법의 숫자/문자열을 상수화하는 리팩토링 프로젝트를 진행했습니다. 처음에는 당장의 기능 개발에 바쁜데 이런 작업을 왜 해야 하는지 의문을 가지는 팀원들도 있었죠. 하지만 프로젝트가 완료된 후, 저희는 다음과 같은 놀라운 변화와 성과를 체감할 수 있었습니다.

• 기능 변경 오류 80% 감소: 가장 인상 깊었던 변화는 비즈니스 로직 변경으로 인한 오류가 현저히 줄었다는 것입니다. 예를 들어, 특정 프로모션 기간을 변경하는 작업이 이전에는 항상 불안했고 실제 버그로 이어진 적도 많았지만, 상수화 후에는 단 한 줄의 코드 수정만으로도 안전하게 배포할 수 있게 되었습니다.
• 신규 개발 속도 20% 향상: 개발자들이 코드를 이해하는 데 드는 시간이 줄어들면서, 새로운 기능을 설계하고 구현하는 속도가 눈에 띄게 빨라졌습니다. 기획팀에서 아이디어를 제안하면 "그거 예전에 하드코딩된 값 때문에 어려웠는데, 지금은 쉽게 가능할 것 같아요!"라는 긍정적인 답변을 더 자주 듣게 되었습니다.
• 온보딩 시간 단축: 신규 개발자가 팀에 합류했을 때, 코드 베이스를 이해하는 데 걸리는 시간이 절반 가까이 줄었습니다. 코드를 읽는 것만으로도 비즈니스 로직을 파악하기 쉬워졌기 때문입니다. 이는 팀의 확장성과 생산성에 직접적인 영향을 미 주었습니다.
• 기획-개발 간 소통 비용 절감: "이 숫자는 뭘 의미하나요?" 같은 질문 자체가 거의 사라졌습니다. 모든 중요한 값들이 명확한 이름을 가지고 코드와 문서에 존재하기 때문에, 서로 다른 팀 간의 오해와 불필요한 논의가 크게 줄어들었습니다.

이러한 변화는 결국 저희 팀이 더 적은 리소스로 더 많은 가치를 창출할 수 있는 핵심 동력이 되었습니다. 코드 품질 개선이 단순한 개발 과제가 아니라, 비즈니스 성과에 직접적으로 기여한다는 것을 깨달은 중요한 경험이었습니다.

마무리하며: 코드 품질은 곧 비즈니스 품질

'마법의 숫자/문자열'은 언뜻 보면 사소해 보이지만, 방치할 경우 눈덩이처럼 불어나 결국 우리 서비스의 안정성과 개발 속도를 좀먹는 주범이 됩니다. 기획자/PM으로서 코드를 직접 작성하지는 않더라도, 이러한 안티패턴의 위험성을 인지하고 적극적으로 문제 해결에 기여하는 역할은 매우 중요합니다.

명확한 요구사항 정의, 개발자와의 활발한 소통, 그리고 코드 품질에 대한 비즈니스적인 이해와 지지는 팀 전체의 생산성을 높이고, 궁극적으로는 더 나은 서비스를 만들어내는 데 결정적인 역할을 할 것입니다. 코드 품질은 곧 비즈니스 품질이라는 점을 기억하시길 바랍니다.

여러분 팀에서는 '마법의 숫자/문자열' 문제를 어떻게 관리하고 계신가요? 혹시 이런 안티패턴으로 인해 겪었던 재미있는 에피소드나 해결 경험이 있다면 댓글로 공유해 주세요!

📌 함께 읽으면 좋은 글

• [이슈 분석] 생성형 AI 시대, 개발자의 역할 변화와 미래 핵심 역량 분석
• [이슈 분석] 우리 팀 기술 발표 자료, 아직도 수작업으로 만드시나요? 효율적인 제작 워크플로우는 없을까요?
• [보안] API 트래픽 폭증에도 끄떡없는 비결: 토큰 버킷과 리키 버킷, 실제 적용 경험으로 본 효율성 차이

이 글이 도움이 되셨다면 공감(♥)과 댓글로 응원해 주세요!
궁금한 점이나 다루었으면 하는 주제가 있다면 댓글로 남겨주세요.