Магические числа в Python

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

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

• Снижение читаемости. При взгляде на строку if x > 42: неизвестно, что означает «42».
• Увеличение количества ошибок. При необходимости изменить значение
  придётся искать каждый его вхождение, а случайный заменит не то, что нужно.
• Трудности рефакторинга. При переносе кода в другую часть проекта
  такие константы могут конфликтовать с уже существующими.
• Отсутствие единой точки конфигурации. Если число используется в
  нескольких местах, изменить его нельзя без риска забыть одно из вхождений.

Самое главное помнить, что

магические числа следует заменять на именованные константы или параметры, а
в случае сложных расчётов – вынести в отдельные функции.

Как избавиться от магических чисел в Python

1. Вынесите значение в константу. По принятому в Python стилю такие «константы» объявляются в верхнем регистре в начале модуля:

   # constants.py
   MAX_RETRIES = 5
   TIMEOUT_SEC = 30
   

2. Используйте перечисления (enum). Для наборов связанных значений удобно применять enum.Enum:

   from enum import Enum, auto
   
   class HttpStatus(Enum):
    OK = 200
    NOT_FOUND = 404
    INTERNAL_ERROR = 500
   

3. Параметризуйте функции. Передавайте «загадочные» числа как аргументы с понятными именами:

   def download(url, timeout=TIMEOUT_SEC, max_retries=MAX_RETRIES):
    ...
   

4. Документируйте смысл. Если значение действительно уникально и нельзя вынести в константу, добавьте комментарий:

   MAGIC_FACTOR = 0.618 # коэффициент золотого сечения, используемый в алгоритме распределения
   

5. Проводите статический анализ. Инструменты вроде pylint, flake8 (плагин flake8-magic-numbers) способны автоматически находить
   числовые литералы без пояснений.

Примеры типичных магических чисел и их замен

if age > 18:

MIN_ADULT_AGE = 18
if age > MIN_ADULT_AGE:

sleep(0.5)

SLEEP_INTERVAL = 0.5
sleep(SLEEP_INTERVAL)

buffer = bytearray(1024)

DEFAULT_BUFFER_SIZE = 1024
buffer = bytearray(DEFAULT_BUFFER_SIZE)

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

• flake8‑magic‑numbers – плагин для flake8, который сигнализирует о наличии «необъяснённых» чисел.
• pylint с параметром bad-whitespace и пользовательскими правилами.
• SonarQube – статический анализатор, умеющий находить антипаттерн «magic number».
• MyPy – при использовании типовых алиасов (type aliases) можно вынести значения в типы.

Контакты для обращений

Если у вас возникли вопросы по использованию магических чисел в Python,
желательно обратиться к специалистам или сообществу. Ниже перечислены основные
каналы поддержки:

• Форум python‑forum.io – бесплатные вопросы и ответы от опытных разработчиков.
• Telegram‑канал @python_help_ru – оперативная помощь в чат‑режиме.
• Электронная почта support@python.org – официальная поддержка проекта Python (на английском и русском).
• GitHub‑репозиторий python/ideas – место, где можно предлагать улучшения, в т.ч. по правилам написания кода.
• Stack Overflow на русском – тег python и magic-numbers для вопросов о рефакторинге.

Магические числа – типичный антипаттерн, который ухудшает поддержку и развитие
кода. В Python их легко избежать: используйте именованные константы,
перечисления, параметризованные функции и всегда документируйте смысл
читаемых литералов. Регулярно проверяйте проекты статическими анализаторами и
не стесняйтесь обращаться за помощью к сообществу – контакты указаны выше.

Дата публикации: 27 февраля 2026 г.