Магические числа в коде: как выявить и устранить ошибки

В программировании термин «магические числа» относится к числовым значениям, используемым непосредственно в коде без явного объяснения их смысла и назначения. Эти числа могут быть источником ошибок и усложнять поддержку и понимание кода разработчиками. Что представляют собой магические числа и как избежать их использования — расскажем в статье.

Что такое магические числа

В программировании под магическими числами понимают числовые литералы (константы), которые используются в коде без пояснений и комментариев. Они не всегда понятны и могут усложнять чтение и сопровождение кода.

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

Кроме того, магические числа могут затруднять совместную работу над проектом. В командах разработчиков такие числовые константы могут стать источником недопонимания и ошибок, поскольку новые или менее опытные члены команды могут не знать значения и назначения этих чисел. Это может вызвать задержки в разработке и увеличить вероятность внесения ошибок.

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

Примеры магических чисел в программировании:

• Константы без пояснений:

В этом примере 3.14159 является магическим числом. Лучше заменить его на именованную константу, чтобы улучшить читабельность и поддерживаемость кода:

• Использование чисел в логике кода:

Здесь 200 также является магическим числом. Для улучшения читаемости и облегчения поддержки кода, рекомендуется использовать именованные константы:

Как они влияют на код

Магические числа могут негативно влиять на код по нескольким причинам:

1. Снижение читаемости кода: Когда в коде используются магические числа, которые не объяснены и не имеют контекста, разработчикам может быть сложно понять, что они означают и почему используются в конкретном месте. Это затрудняет работу с кодом, особенно в процессе его обзора или модификации.
2. Усложнение поддержки и сопровождения кода: Если значение магического числа нужно изменить, разработчику придётся искать и изменять его во всех местах использования, что может быть особенно проблематично в большом кодовом базе, где это число может использоваться в нескольких файлах. Это увеличивает риск ошибок и усложняет тестирование, так как изменения в одной части программы могут непредсказуемо повлиять на другие её части.
3. Ограничение гибкости и расширяемости кода: Когда числовые значения «зашиты» в код, изменение бизнес-логики или добавление новых функций становится сложнее. Например, если число 10 используется для определения количества попыток входа, а это значение позже нужно изменить на 15, вам придется искать и заменять его в каждом месте кода. При изменении требований необходимо пересматривать и обновлять весь код, что требует дополнительных затрат времени и усилий.
4. Проблемы при совместной работе: Разные разработчики могут использовать одинаковые числа для разных целей, что приводит к путанице и увеличивает вероятность ошибок. Это снижает эффективность командной работы и замедляет процесс разработки.
5. Усложнение тестирования: Тесты должны учитывать все возможные значения магических чисел и их влияние на программу. Изменение этих чисел требует переписывания тестов, что затрудняет обеспечение качества кода.

Как их выявить в коде

Существует несколько способов выявления магических чисел в коде:

1. Кодовый анализ: Применяйте инструменты статического анализа кода, которые позволят выявить «магические числа». Эти инструменты анализируют код, не выполняя его, и могут указывать на числовые литералы, которые не задокументированы или не используют именованные константы.
2. Кодовые ревью: Во время проверки кода обращайте внимание на все числовые значения, которые используются в логике программы. Если какое-то значение не объяснено в комментариях и не является частью именованной константы, то это может быть так называемое «магическое число».

   Обсудите такие случаи с командой разработчиков и предложите заменить «магические числа» на осмысленные именованные константы или переменные. Это повысит читаемость и облегчит поддержку кода, поскольку каждому числовому значению будет дано понятное имя, отражающее его назначение.

3. Поиск по коду: Используйте функции поиска в вашей интегрированной среде разработки (IDE) или текстовом редакторе, чтобы найти числовые значения в коде. Вы можете искать конкретные числа или шаблоны чисел, например, с помощью регулярных выражений, которые могут указывать на потенциальные «магические числа».
4. Профилирование и рефакторинг:При профилировании и рефакторинге кода уделите особое внимание участкам, где используются числовые значения. При обнаружении магических чисел определите, могут ли они быть заменены на именованные константы или переменные, чтобы улучшить структуру и ясность кода.
5. Использование линтеров: Настройте линтеры, например, ESLint для JavaScript или Pylint для Python, чтобы они обнаруживали и помечали магические числа. Линтеры можно настроить на определённые правила, которые помогут выявлять такие числа в коде.

Вот, например, ещё один наглядный пример магических чисел:

Выявленные магические числа (1, 2, 3, 0.9, 0.8, 0.5) можно заменить на именованные константы:

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

Как избежать их использования

Чтобы избежать использования магических чисел в программировании, можно применять несколько подходов и лучших практик:

1. Использование именованных констант

   Заменяйте числовые литералы именованными константами. Это делает код более читаемым и понятным.

   # Плохо if discount_type == 1: discount = 0.1 # Хорошо DISCOUNT_TYPE_STANDARD = 1 DISCOUNT_STANDARD = 0.1 if discount_type == DISCOUNT_TYPE_STANDARD: discount = DISCOUNT_STANDARD

2. Комментирование кода

   Если использование числового литерала неизбежно, добавляйте комментарии, объясняющие его значение и назначение. Однако, по возможности, старайтесь минимизировать использование числовых литералов, даже если они прокомментированы, поскольку именованные константы обычно предпочтительнее для повышения читаемости кода.

   # Плохо timeout = 300 # Хорошо timeout = 300 # Таймаут соединения в секундах

3. Использование перечислений (enum)

   В языках, поддерживающих перечисления (enum), используйте их для представления набора связанных констант.

   from enum import Enum class DiscountType (Enum): STANDARD = 1 PREMIUM = 2 VIP = 3 discount_type = DiscountType. STANDARD if discount_type == DiscountType. STANDARD: discount = 0.1

4. Использование конфигурационных файлов

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

   JSON:

   { «standard_discount»: 0.1, «premium_discount»: 0.2, «vip_discount»: 0.3 }

   PYTHON:

   import json with open ('config.json') as config_file: config = json. load (config_file) discount = config["standard_discount"]

5. Использование глобальных констант

   Для часто используемых числовых значений можно определять глобальные константы в отдельном модуле.

Пример (constants.py):

Применение этих практик позволяет создавать более понятный, удобный для поддержки и гибкий код. Это не только делает код более доступным для понимания и сопровождения, но и снижает риск возникновения ошибок при внесении изменений в будущем, обеспечивая более устойчивое и предсказуемое поведение системы.

Как устранить магические числа

Шаг 1: Обнаружение магических чисел

Первым делом нужно найти все магические числа в вашем коде. Для этого можно использовать ручной обзор кода, статический анализ с помощью инструментов или линтеров. Статический анализ и линтеры особенно полезны, так как они автоматически обнаруживают числовые литералы, не обоснованные именованными константами или комментариями.

Шаг 2: Понимание контекста

Определите значение и назначение каждого магического числа. Вам нужно разобраться, почему оно используется, какое значение оно имеет и где ещё может встречаться в коде программы.

Шаг 3: Замена магических чисел на именованные константы

Создайте именованные константы, которые будут описывать назначение каждого числового значения. Именованные константы должны иметь понятные и значимые названия.

Шаг 4: Вынесение значений в конфигурационные файлы

Если числовые значения могут меняться в зависимости от среды или конфигурации, рекомендуется вынести их в отдельные конфигурационные файлы. Это позволяет легко изменять значения без необходимости модификации исходного кода, что повышает гибкость и упрощает управление конфигурацией.

Пример устранения магических чисел:

Исходный код с магическими числами:

Шаг 1 и 2: Обнаружение и понимание контекста:

Мы видим магические числа 1, 2, 3 для типов скидок и 0.9, 0.8, 0.5 для значений скидок.

Шаг 3: Замена магических чисел на именованные константы:

Создадим константы для каждого значения:

Шаг 4: Вынесение значений в конфигурационные файлы:

Создадим конфигурационный файл config. json:

Изменим код, чтобы использовать конфигурационный файл:

Типичные ошибки и как их исправить

Ошибка: Повторяющиеся магические числа

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

Исправление: Создайте константу для числа 18 и используйте её в коде:

Ошибка: Неочевидное значение магического числа

Магические числа могут не нести явного смысла, делая код трудным для понимания.

Исправление: Создайте константу для числа π и используйте её в коде:

Ошибка: Сложность изменения

Изменение значения магического числа может потребовать изменения кода во многих местах, что увеличивает вероятность ошибок.

Исправление: Создайте константу для значения скидки и используйте её в коде:

Ошибка: Трудности тестирования

Тестирование кода, содержащего магические числа, усложняется необходимостью учитывать все возможные значения этих чисел, что увеличивает вероятность пропуска ошибок.

Исправление: Создайте константу для порога количества и используйте её в коде:

Ошибка: Неоднозначные магические числа

Использование чисел без пояснений может привести к неоднозначности, особенно когда одно и то же число используется в разных контекстах с разными значениями.

Исправление: Создайте константы для кодов ошибок и используйте их в коде:

Избавление от магических чисел в коде делает его более понятным, удобным для поддержки и гибким. Чтобы избежать ошибок, связанных с использованием магических чисел, важно использовать именованные константы, комментировать код и выносить значения в конфигурационные файлы. Это ключевые стратегии, которые сделают ваш код более надёжным и легко поддерживаемым.

Главное, что нужно знать

Что такое магические числа?

Магические числа — это числовые литералы в коде, которые используются непосредственно в коде без пояснений, комментариев или контекста, объясняющего их значение. Они могут затруднять понимание и сопровождение кода, поскольку их назначение и значение не очевидны.

Проблемы, связанные с магическими числами

Магические числа снижают читаемость кода, делают его менее гибким и более сложным в поддержке. Они также могут привести к ошибкам, особенно если число используется в нескольких местах.

Как выявить магические числа?

Магические числа можно обнаружить, просматривая код вручную, используя линтеры, инструменты статического анализа кода или проводя тщательные кодовые ревью.

Как заменить магические числа?

Вместо числовых литералов следует использовать именованные константы с понятными названиями. В некоторых случаях полезно добавлять комментарии, использовать перечисления (enum) для связанных наборов констант или выносить числовые значения в конфигурационные файлы.

Практики для предотвращения использования магических чисел

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