7.3 Магические числа (Magic numbers)

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

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

Магические числа могут привести к множеству проблем в программе:

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

2. Помимо необходимости изменения всех значений магического числа, может возникнуть проблема с разными по смыслу, но одинаковыми по значению магическими числами. Например, число 8 может обозначать как количество бит в байте, так и количество байт, занимаемых значением типа int в 64-х битной системе. Для того чтобы определить, какой смысл заложен в конкретное магическое число, потребуется дополнительное время для анализа контекста использования. Если при необходимости изменения магического числа ориентироваться только на его значение, это с большой вероятностью приведет к появлению ошибок.

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

4. Использование магических чисел может привести к проблемам с переносимостью программы по причине того, что размеры типов данных в 32-битной версии программы и в 64-битной версии будут отличаться. Например, такой код в 64-битной версии программы приведет к ошибке во время выполнения:

const size_t COUNT = 10;

int arr[COUNT];

memset(arr, 0, COUNT * 4);

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

memset(arr, 0, COUNT * sizeof(arr[0]));

либо

memset(arr, 0, sizeof(arr));

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

7.4 Бездумное комментирование

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

// Пример 7.1 - пример бездумного комментирования

// Если а больше чем b

if(a>b) {}

// Увеличить переменную х на единицу

++x;

// Цикл for, в котором переменная увеличивается от 0 до 9 включительно

for(int i = 0; i != 10; ++i) {}

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

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

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