Ядро 3ОС. Система нотации

Данный раздел документации 3ОС содержит формальное описание системы нотации, выработанной для символического обозначения конструкций языка, использующегося при разработке ядра 3ОС. Данный подход ориентирован на смысловую обозримость кода и заключается в том, чтобы создать такую оптимальную запись кода, которая бы отняла у разработчика минимум времени и сил не только в период его (кода) создания, но и в период его отладки, сопровождения и т.п.

Основные требования, предъявляемые к системе нотации, можно сформулировать следующим образом:

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

Имена объектов кода (функций, структур, переменных) должны удовлетворять следующим критериям:

• отражать смысл назначения объекта кода
• по-возможности, быть короткими
• в длинных именах гласные и часть не несущих информации согласных (если это не является критичным для понимания) опускаются
• сложные имена составляются в иерархическом порядке (сверху - вниз) согласно следующему образцу:
    КореньВетвь (переменные) или КореньВетвь_Действие (функции)

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

В общем случае имя объекта кода состоит из:

1. префикса, несущего информацию о типе объекта (опционально)
2. описания, отражающего смысл назначения объекта (присутствует всегда)
3. суффикса, определяющего характер производимых объектом действий (опционально)

Используются следующие соглашения*:

1. Составные типы данных (структуры кода) именуются с лидирующим префиксом, который состоит из одного или более строчных символов, соответствующих семантическому представлению базового типа объекта, отделенных от имени объекта символом подчеркивания:
• классы (class) объявляются с префиксом 'c_'
• структуры (struct) объявляются с префиксом 's_'
• объединения (union) объявляются с префиксом 'u_'
• перечисления (enum) объявляются с префиксом 'e_'
2. Локальные переменные кода именуются с префиксом, состоящим из одного или более строчных символов, соответствующих смысловому представлению базового типа объекта, при этом символ подчеркивания не ставится:
• логические (булевы) переменные (bool) имеют префикс 'l'
• целые (натуральные) числа, независимо от их разрядности, имеют префикс 'n'
• вещественные числа, также независимо от их разрядности, имеют префикс 'f'
• символьные (строковые) переменные (char) имеют префикс 'c'
• нуль-терминированные строковые переменные (char *) имеют префикс 'z'
• указатели типа (*) имеют, помимо префикса типа, также префикс 'p'
• адресные указатели (void *) объявляются с префиксом 'v'
• массивы, помимо префикса типа, имеют также префикс 'a'
Кроме того, имеется ряд дополнительных соглашений:
• однобайтовые целые переменные (byte) объявляются с префиксом 'b'
• двухбайтовые целые переменные (word) объявляются с префиксом 'w'
• четырехбайтовые целые переменные (dword) объявляются с префиксом 'dw'
3. Глобальные переменные кода именуются подобно локальным с дополнительным префиксом 'g_'
4. Константы (const) именуются с префиксом 'k_'
5. Макрокоманды именуются с префиксом 'm_'
6. Функции префикса не имеют, однако могут иметь суффикс, обозначающий характер предполагаемых действий. За исключением булевых функций, которые именуются без суффикса, но с использованием префикса 'Is'

* Приведенные правила именования объектов кода, как и любые другие правила, могут иметь исключения.

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

Список используемых префиксов*

  c_      - class
  s_      - struct
  u_      - union
  e_      - enum
 
  b       - byte
  w       - word
  dw      - dword

  c       - char
  z       - char * 
  n       - int [long, ...]
  f       - float [double, ...]

  a[..]   - массив, где [..] - префикс типа
  p[..]   - указатель, где [..] - префикс типа
  v       - void *
  l       - bool

  k_      - константа   
  m_      - макрокоманда
  g_[..]  - глобальная переменная, где [..] - префикс типа


  * Для обозначения префиксов используются строчные литеры

При разработке кода ядра 3ОС, во избежание ошибок неявного объявления, все переменные инициализируются в явном виде. Для обеспечения легкости чтения кода, помимо использования системы нотации, также применяется соответствующее форматирование кода. Вследствие чего, все фрагменты кода ядра оформляются одинаково. Для упрощения записи кода рекомендуется вложенные структуры и объединения объявлять в анонимном виде.