July 20, 2025

🧙‍♂️ 마법의 문자열/숫자 남용: 예측 불가능한 코드와 유지보수의 덫

네이밍

아키텍처

TypeScript

Lint/Formatter

Summary

코드 내 의미 없는 문자열/숫자(마법의 리터럴)는 가독성, 유지보수성을 저해하고 버그를 유발합니다. 상수를 정의하고, 열거형 또는 객체로 관리하여 코드의 의도를 명확히 하고 재사용성을 높여야 합니다.

Why Wrong?

코드 내에 의미가 불분명한 문자열("active", "pending", "admin")이나 숫자(예: 1, 0, 999 같은 상태 코드, 특정 간격 값)를 직접 사용하는 것은 '마법의 리터럴(Magic Literals)'이라고 불리는 대표적인 안티패턴입니다. 이러한 리터럴들은 다음과 같은 문제를 야기합니다:

가독성 저하: 개발자가 코드의 의도를 파악하기 어렵게 만듭니다. if (status === 1)에서 1이 정확히 무엇을 의미하는지 문맥 없이는 알기 어렵습니다.
유지보수성 악화: 특정 값이 변경되어야 할 때, 코드베이스 전체를 검색하여 모든 인스턴스를 수동으로 변경해야 합니다. 이는 시간이 많이 소요되며, 누락이나 오타로 인한 버그를 유발하기 쉽습니다. (DRY 원칙 위배)
잠재적 버그 발생: 오타("acive" 대신 "active")가 발생하더라도 런타임에만 문제가 드러나거나, 아예 발견되지 않아 예측 불가능한 동작을 유발할 수 있습니다. 문자열 비교는 특히 이러한 문제에 취약합니다.
리팩토링의 어려움: 관련 로직이 여러 곳에 흩어져 있으면 리팩토링 시 변경 범위 파악이 어렵고 오류 발생 확률이 높아집니다.
타입 안전성 저해: 특히 TypeScript와 같은 정적 타입 언어에서 문자열 리터럴을 사용하는 것은 컴파일 시점에 타입을 강제하기 어렵게 만들어 타입 안정성을 약화시킵니다.

How to Fix?

모든 '마법의 리터럴'을 의미 있는 이름의 상수로 정의하고 한 곳에서 관리해야 합니다. 이는 코드의 가독성을 높이고, 한 곳에서 값을 관리할 수 있게 하여 유지보수를 용이하게 합니다.

상수(Constants) 사용: 재사용되거나 의미가 중요한 모든 리터럴 값을 명명된 상수로 추출하여 사용합니다. 이는 코드의 의도를 명확히 합니다.
객체(Object) 또는 열거형(Enum) 사용: 관련된 상수들을 그룹화하여 객체나 열거형으로 관리합니다. 특히 TypeScript에서는 enum이나 union type을 활용하여 특정 값들의 집합을 명시적으로 표현하고 타입 안정성과 자동 완성 기능을 제공할 수 있습니다.
매핑 객체(Mapping Object) 사용: 서버 응답 코드나 특정 상태 값에 따라 다른 동작을 수행해야 할 경우, 매핑 객체를 사용하여 가독성을 높이고 조건문의 복잡성을 줄일 수 있습니다.
린터(Linter) 규칙 활용: ESLint나 TSLint와 같은 린터 도구에서 'no-magic-numbers'나 커스텀 규칙을 설정하여 코드에 마법의 리터럴이 사용되지 않도록 강제할 수 있습니다. 이러한 방법을 통해 코드의 의도를 명확히 하고, 잠재적인 버그를 줄이며, 장기적인 관점에서 코드의 응집도와 유지보수성을 크게 향상시킬 수 있습니다.

Before Code (Bad)

// components/UserProfile.jsx
import React from 'react';

function UserProfile({ status, userType }) {
  let statusMessage = '';
  if (status === 1) { // 1이 뭘까? 'active'를 의미하는 건가?
    statusMessage = '사용 중';
  } else if (status === 0) { // 0은? 'inactive'?
    statusMessage = '비활성';
  } else {
    statusMessage = '알 수 없음';
  }

  const getProfileStyle = () => {
    // 하드코딩된 값들
    if (userType === 'admin') {
      return { border: '2px solid red', padding: '10px' };
    } else if (userType === 'guest') {
      return { border: '1px solid gray', opacity: 0.7 }; // 0.7의 의미는?
    }
    return {};
  };

  return (
    <div className={`user-profile ${userType}`}>
      <h3>사용자 프로필</h3>
      <p>상태: {statusMessage}</p>
      <div style={getProfileStyle()}>
        <p>타입: {userType}</p>
      </div>
      {/* 다른 프로필 정보들 */}
    </div>
  );
}

export default UserProfile;

After Code (Good)

// constants/user.js
export const USER_STATUS = {
  ACTIVE: 1,
  INACTIVE: 0,
  UNKNOWN: -1, // 명확한 기본값 추가
};

export const USER_TYPE = {
  ADMIN: 'admin',
  GUEST: 'guest',
  REGULAR: 'regular',
};

// components/UserProfile.jsx
import React from 'react';
import { USER_STATUS, USER_TYPE } from '../constants/user'; // 상수 임포트

function UserProfile({ status, userType }) {
  let statusMessage = '';
  switch (status) {
    case USER_STATUS.ACTIVE:
      statusMessage = '사용 중';
      break;
    case USER_STATUS.INACTIVE:
      statusMessage = '비활성';
      break;
    default:
      statusMessage = '알 수 없음';
  }

  const getProfileStyle = () => {
    switch (userType) {
      case USER_TYPE.ADMIN:
        return { border: '2px solid red', padding: '10px' };
      case USER_TYPE.GUEST:
        return { border: '1px solid gray', opacity: 0.7 }; // 0.7은 여전히 마법의 숫자일 수 있으므로 필요시 상수로 추출
      default:
        return {};
    }
  };

  return (
    <div className={`user-profile ${userType}`}>
      <h3>사용자 프로필</h3>
      <p>상태: {statusMessage}</p>
      <div style={getProfileStyle()}>
        <p>타입: {userType}</p>
      </div>
      {/* 다른 프로필 정보들 */}
    </div>
  );
}

export default UserProfile;

// TypeScript 환경이라면 다음과 같이 타입 안정성을 더 높일 수 있습니다.
/*
// types/user.ts
export enum UserStatus {
  ACTIVE = 1,
  INACTIVE = 0,
  UNKNOWN = -1,
}

export type UserType = 'admin' | 'guest' | 'regular';

// components/UserProfile.tsx
import React from 'react';
import { UserStatus, UserType } from '../types/user';

interface UserProfileProps {
  status: UserStatus;
  userType: UserType;
}

function UserProfile({ status, userType }: UserProfileProps) {
  let statusMessage: string;
  switch (status) {
    case UserStatus.ACTIVE:
      statusMessage = '사용 중';
      break;
    case UserStatus.INACTIVE:
      statusMessage = '비활성';
      break;
    default:
      statusMessage = '알 수 없음';
  }

  const getProfileStyle = () => {
    switch (userType) {
      case 'admin': // TypeScript의 리터럴 타입 추론을 활용
        return { border: '2px solid red', padding: '10px' };
      case 'guest':
        return { border: '1px solid gray', opacity: 0.7 };
      default:
        return {};
    }
  };

  return (
    <div className={`user-profile ${userType}`}>
      <h3>사용자 프로필</h3>
      <p>상태: {statusMessage}</p>
      <div style={getProfileStyle()}>
        <p>타입: {userType}</p>
      </div>
    </div>
  );
}

export default UserProfile;
*/

마법의 숫자를 상수로 정의하여 코드를 더 읽기 쉽고 유지보수하기 좋게 만드는 것에 대한 모범 사례를 설명합니다.

https://refactoring.com/smells/magic-number.html

TypeScript에서 `enum`을 사용하여 관련된 상수 집합을 정의하고 타입 안정성을 확보하는 방법을 설명합니다.

https://www.typescriptlang.org/docs/handbook/enums.html

ESLint `no-magic-numbers` 규칙을 통해 코드 내 하드코딩된 숫자 리터럴 사용을 방지하여 가독성과 유지보수성을 높이는 방법을 설명합니다.

https://eslint.org/docs/latest/rules/no-magic-numbers