Магический номер

Магический номер (англ. magic number) – это «зашифрованное» числовое значение,
которое появляется в коде без поясняющих комментариев или именованных констант.
Такие числа часто вызывают недопонимание, усложняют поддержку и повышают риск ошибок.

Почему магические номера считаются плохой практикой?

• Неочевидность – без контекста трудно понять, зачем именно использовано число 42 или 0.75.
• Повторяемость – одно и то же значение может встречаться в разных местах кода, и при изменении его необходимо искать и менять каждый случай вручную.
• Трудности тестирования – в юнит‑тестах часто приходится «угадывать», какие значения являются «правильными», что приводит к хрупким тестам.
• Нарушение принципов чистого кода – магические числа противоречат принципу Self‑Documenting Code (самодокументируемого кода).

Где обычно встречаются магические номера?

1. В условных операторах (if, switch) – например, if (status == 3).
2. В циклых конструкциях – for (int i = 0; i < 10; i++).
3. При работе с форматами файлов – «магическое» значение заголовка, например, 0xCAFEBABE в Java‑классе.
4. В математических формулах – коэффициенты, константы, коэффициенты затухания и т;п.
5. В конфигурационных параметрах, которые «зашиты» в коде вместо внешних файлов.

Как правильно заменять магические номера?

Выделить в именованную константу

Самый простой и распространённый способ – объявить const (или final, #define и т.п.) с понятным именем.

// Java
private static final int MAX_RETRY_COUNT = 5;

// C#
private const int MaxRetryCount = 5;
// Python
MAX_RETRY_COUNT = 5

Группировать связанные константы в отдельный класс/модуль

Если набор магических чисел относится к одной области (например, настройки сети), имеет смысл собрать их в отдельный файл:

// config.py
class NetworkConfig:
 TIMEOUT_SECONDS = 30
 MAX_PACKET_SIZE = 1024
 RETRY_DELAY_MS = 250

Добавлять комментарии при невозможности вынести в константу

Иногда значение зависит от внешних факторов (например, фиксированный код ошибки от сторонней API). В таком случае следует добавить поясняющий комментарий:

// Ошибка 404 – «Не найдено» (HTTP)
if (responseCode == 404) { ... } // 404 – Not Found

Использовать перечисления (enum) для наборов взаимосвязанных чисел

// C#
enum HttpStatus
{
 Ok = 200,
 NotFound = 404,
 InternalServerError = 500
}

Инструменты для обнаружения магических номеров

• SonarQube – статический анализатор, который помечает «hard‑coded numbers».
• PMD (rule MagicNumber) – для Java‑проектов.
• ESLint с плагином no-magic-numbers – для JavaScript/TypeScript.
• ReSharper – для .NET, умеет находить и предлагать заменить магические числа.
• pylint – правило magic-number (можно включить через конфиг).

Примеры «проверенных» магических номеров и их замена

Пример 1: Пороговое значение валидации

Исходный код:

if (age < 18) {
 throw new IllegalArgumentException("Too young");
}

После рефакторинга:

private static final int MINIMUM_AGE = 18;

if (age < MINIMUM_AGE) {
 throw new IllegalArgumentException("Too young");
}

Пример 2: Коэффициент скидки

// Плохой вариант
double discount = price * 0.85; // 15% скидка

// Хороший вариант
private static final double DISCOUNT_RATE = 0.15;
double discount = price * (1 ⎯ DISCOUNT_RATE);

Пример 3: Размер буфера при чтении файла

// Плохой вариант
byte[] buffer = new byte[4096];

// Хороший вариант
private static final int DEFAULT_BUFFER_SIZE = 4 * 1024; // 4 KiB
byte[] buffer = new byte[DEFAULT_BUFFER_SIZE];

Практические рекомендации

1. Всегда задавайте вопрос: «Что означает это число?» Если ответ не очевиден – вынесите его в константу.
2. Соблюдайте единый стиль именования: UPPER_SNAKE_CASE для глобальных констант, PascalCase для enum‑ов.
3. Не переусердствуйте: небольшие «технические» числа (например, 0, 1 в индексах массивов) обычно оставляют без констант, если их смысл ясен из контекста.
4. Документируйте внешние магические номера: если значение задаётся сторонней системой, укажите источник (спецификация, RFC, API‑документация).
5. Регулярно запускайте статический анализ: интегрируйте инструменты в CI/CD, чтобы новые магические номера не попадали в кодовую базу.

Магические номера – это один из самых простых, но в то же время коварных источников технического долга. Их своевременное выявление и замена на именованные константы, перечисления или конфигурационные параметры делает код более читаемым, упрощает поддержку и снижает вероятность ошибок. Используйте перечисленные выше подходы и инструменты, и ваш проект станет «проверенным» в плане качества кода.

Автор статьи – виртуальный помощник ChatGPT, 2026 год.