Порядок в коде – порядок в голове

Ещё одна статья от нашего друга ice, стиль авторский.

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

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

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

Оформление кода я покажу на примере, так как лучше один раз показать, чем писать кучу букв тут. Данное оформление справедливо только для “cи” кода,
и оно хорошо применимо для любой платформы.

Итак каких же стандартов я придерживаюсь в таком коде?

  1. Типы записываются в верхнем регистре
  2. Имена переменных, и всех ключевых слов начинаются с заглавной буквы
  3. Тип в именах переменных указывается только для указателей, pData или ppData (остальные типы считаю указывать избыточным)
  4. Все элементы функции (тип, имя, аргументы) начинаются с новой строки
  5. Между кодовыми блоками ({}) ставятся переносы строки
  6. Функции которые предполагается включать в заголовочные файлы, должны начинаться с имени “.с” файла (VfsSomeFunction)
  7. Функции которые не используются в интерфейсах, должны быть определены как static, что бы не захламлять пространство имен
  8. В заголовочных файлах использовать конструкции #ifndef __VFS__ #define __VFS__, в имени участвует имя модуля
  9. Переменные с именем в один литерал (i,j и т.д.) записываются в нижнем регистре
  10. Имена макросов записываются в верхнем регистре
  11. Весь код должен быть пронизан ASSERT
  12. Кодовые блоки ({ или }) или ключевые слова, начинаются всегда с новой строки
  13. Глобальные переменные именуются с “g_”, например g_SomeVariable
  14. Глобальные переменные не должны находиться в хидерах, если нужно передать такую переменную в другой модуль, то использовать для этого функцию

Так как код планируется кросплатформенный, то хорошо бы определиться с типами, так как если брать windows, то 4-байтную переменную можно определить кучей типов DWORD, UINT и еще не весть что.

Так как структуры планируется именовать в верхнем регистре то у меня создан такой файлик

Тут заданы все необходимые простые типы, которые могут вам понадобиться и все в едином стандарте (верхний регистр)

Отдельный заголовочный файл для отладочных сообщений

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

Нам пришлось ввести конструкцию else, которая создает лишний код, и когда мы сделаем релиз, то код с else останется.

Да и это некрасивый код. Гораздо приятнее он выглядит с ASSERT, в нем сразу реализовано это условие проверки, что если не так. То логирует номер строки и имя файла, и не нужно выдумывать сообщение о падении, все кратко и просто.

2 thoughts on “Порядок в коде – порядок в голове

  1. Про вывод сообщений:
    wchar_t text_buffer[20] = { 0 };
    swprintf(text_buffer, _countof(text_buffer), L”%d”, your.variable);
    OutputDebugString(text_buffer);
    Ну а там уже в красивую функцию завернуть.

Добавить комментарий