🗊Презентация Стандартны оформления программного кода

Стандартны оформления программного кода Лекция по дисциплине «Программирования на C»

Стиль кодирования Стандарт оформления кода – набор правил и соглашений, используемых при написании исходного кода на некотором языке программирования. Наличие общего стиля программирования облегчает понимание и поддержание исходного кода, написанного более чем одним программистом, а также упрощает взаимодействие нескольких человек при разработке программного обеспечения. Целью создания стандарта кодирования является добиться такого положения, когда программист мог бы дать заключение о функции, выполняемой конкретным участком кода, а в идеале — также определить его корректность, изучив только сам этот участок кода или, во всяком случае, минимально изучив другие части программы. Иными словами, смысл кода должен быть виден из самого кода, без необходимости изучать контекст. Поэтому стандарт кодирования обычно строится так, чтобы за счёт определённого визуального оформления элементов программы повысить информативность кода для человека.

Стандарт Обычно, стандарт оформления кода описывает: способы выбора названий и используемый регистр символов для имён переменных и других идентификаторов: запись типа переменной в её идентификаторе (венгерская нотация); регистр символов (нижний, верхний, «верблюжий», «верблюжий» с малой буквы), использование знаков подчёркивания для разделения слов; стиль отступов при оформлении логических блоков — используются ли символы табуляции, ширина отступа; способ расстановки скобок, ограничивающих логические блоки; использование пробелов при оформлении логических и арифметических выражений; стиль комментариев и использование документирующих комментариев. Вне стандарта подразумевается: отсутствие магических чисел; ограничение размера кода по горизонтали (чтобы помещался на экране) и вертикали (чтобы весь код файла держался в памяти), а также функции или метода в размер одного экрана.

Венгерская нотация Венгерская нотация – соглашение об именовании переменных, констант и прочих идентификаторов в коде программ. Своё название венгерская нотация получила благодаря программисту компании Microsoft венгерского происхождения Чарльзу Симони. Эта система стала внутренним стандартом Майкрософт. Суть венгерской нотации сводится к тому, что имена идентификаторов предваряются заранее оговорёнными префиксами, состоящими из одного или нескольких символов. При этом, как правило, ни само наличие префиксов, ни их написание не являются требованием языков программирования, и у каждого программиста (или коллектива программистов) они могут быть своими.

Таблица префиксов

Cтили написания составных слов CamelCase — стиль написания составных слов, при котором несколько слов пишутся слитно без пробелов, при этом каждое слово пишется с заглавной буквы. Стиль получил название CamelCase, поскольку заглавные буквы внутри слова напоминают горбы верблюда. Альтернативным способом создания имён в программном код spinal_case (несколько слов разделяются символом нижнего подчеркивания '_') и snake-case (используется тире '-').

ПРИМЕР Используемый язык Имена файлов, проектов, папок, сам текст программы в том числе и комментарии должны быть записаны и использованием букв латинского (английского) алфавита. Не допускается использование транслита — передача текста с помощью чужого алфавита. Все должно быть написано с использованием правил английского языка. Почему?

Имена файлов и папок Имена файлов должны отражать реализацию/объявление модулей/функций. Используется CamelCase. Имена файлов должны быть уникальными в пределах проекта. Используйте следующие расширения: *.cpp – C++; *.c – C; *.h – заголовочный файл; *.inl – inline файл; Имена папок должны быть в стиле snake_case, но старайтесь использовать одно слово в именах, чтобы не использовать знак подчеркивания. Почему нет побелов?

Оформление логических блоков Все исходные файлы (файлы кода) должны иметь следующую структуру: - Авторство (copyright); - Описание (documentation); - Подключаемые заголовочные файлы (include headers); - Предварительное объявление (forward declarations); - Локальное объявление типов (locally declared types); - Локальные константы и макросы (local constants and macros); - Локальные статически и глобальные переменные (local static / global variables). - Реализация функций (functions implementation). Подключайте минимально требуемое количество заголовочных файлов. Не руководствуйтесь словами: "на всякий случай". Почему?

Оформление заголовочного файла Структура заголовочного файла: Информация о модуле; Проверка множественного включения (#ifdef); Препроцессорные директивы (#include, #define); Предварительное объявление (forward declarations); Локальное объявление типов/структур (locally declared types); Проверка множественного включения (#endif).

Типы переменных Используйте следующие базовые типы:

Имена переменных В именах переменных возможно присутствие префиксов 'g_' для обозначение глобальных переменных и 's_' – для статических. Имена переменных должны отражать содержащую информацию. Используемый стиль сamelCase (первая буква всегда маленькая). Не используйте знак подчеркивания '_', кроме тех случаев, где это явно разрешено. Не используйте придуманные аббревиатуры, разрешено только применять только известные, например, rgb, lcd.

Константы Все буквы в имени констант должны быть в верхнем регистре (большими) и в качестве разделителей должны быть использованы знаки подчеркивания '_'. Данное правило применяется только к макросам и базовым типам.

Макросы Все буквы в имени макросов должны быть в верхнем регистре (большими) и в качестве разделителей должны быть использованы знаки подчеркивания '_‘.

Макросы (продолжение) Это позволит использовать макрос в следующей конструкции:

Функции (размер, имена) Размер функции не должен быть большим, это осложняет понимания. Если функция слишком большая следует применить рефакторинг для уменьшения размера. Имена функций должны иметь префик, который обозначает модуль/библиотеку, к которому он относится. Также это требуется для исключения одинаковых имен функций в программе. Исключением является стандартные функции и функции из сторонних библиотек. Также как и имя переменных имена функции несут смысловую нагрузку. Cтиль CamelCase.

Форматирование кода Длина строк кода Длина строк кода не должна превышать 100 символов. В случае слишком длинной строки она может быть разделена на несколько строк, что влечет за собой уменьшения читабельности. Табуляция Не используйте знак табуляции, только в качестве 4 пробельных символов. Почему? Отступы Код должен быть всегда отформатирован – код в каждом блоке должен быть смещен относительно символа начала и конца блока. В случает, если вложенность достигает 4-5, то возможно следует провести рефакторинг.

Пробелы Используйте пробелы для разделения операторов и их операндов.

Пробелы (продолжение)

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

Комментарии (продолжение) Другие типы тегов-комментариев: FIXME – код должен быть исправлен. HACK – обходной приём (workaround). UNDONE – откат ("roll back") на предыдущую версию кода. XXX – предупреждение для программистов об сложно или опасном коде UX – уведомление о нетривиальном коде Замечание. Обходной приём, workaround, паллиатив, на техническом жаргоне — «костыль» — относительно быстрое и простое решение проблемы, применяемое для срочного устранения её последствий, но не влияющее на причины её возникновения. Обходной приём обычно является временным, или неполным решением, не отвечающим требованиям к дальнейшему развитию системы, требующим в дальнейшем замены на окончательное, более полное (wikipedia).