Д: Свод стилистических соглашений
ПРИЛОЖЕНИЕ Д
С В О Д С Т И Л И С Т И Ч Е С К И Х ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ С О Г Л А Ш Е Н И Й ~~~~~~~~~~~~~~~~~~~
----------------------------------------------------------------
Содержимое этого приложения находится в общественном пользовании. Мы поощряем его публикацию без ограничений при условии ссылки на первоисточник.
ОТСТУПЫ И ПРОПУСКИ.
1 пробел между : и именем 2 пробела между именем и его комментарием * 2 пробела или новая строка после комментария до тела определения * 3 пробела между именем и телом определения, если комментарии не используются 3 пробела отступа для каждой из последовательных строк (или кртаные тройке отступы для выделения вложенности) 1 пробел между словами/числами внутри фразы 2 или 3 пробела между фразами 1 пробел между последним словом и ; 1 пробел между ; и IMMEDIATE (при необходимости)
Не ставить пустых строк между определениями, кроме случаев разграничения существенных групп определений.
* Часто наблюдаемая альтернатива - 1 пробел между именем и комментарием и 3 - между комментарием и определением. Более либеральный подход использует по 3 пробела до и после комментария. Что бы Вы ни выбрали, будьте последовательны. - 294 -
АББРЕВИАТУРЫ ДЛЯ СТЕКОВЫХ КОММЕНТАРИЕВ.
n чило одинарной длины со знаком d число двойной длины со знаком u чило одинарной длины без знака ud число двойной длины без знака t тройная длина q учетверенная длина c 7 (или 8)-битный символ b 8-ми битный байт ? булевский флаг, или: t= (true) истина f= (false) ложь a или adr или адр адрес acf адрес поля кода apf адрес поля параметров ' (в качестве префикса) адрес чего-либо s d (как пара) источник приемник lo hi нижняя- верхняя-граница (включительно) # число (количество) o (offset) смещение i индекс m маска x безразлично (для структур данных)
"Смещение" - это разница, выраженная в абсолютных единицах, например, байтах. "Индекс" - это разница, выраженная в логических единицах, например, элементах записи.
КОММЕНТАРИИ ДЛЯ ВХОДНОГО ПОТОКА.
c одиночный символ, выделенный пробелами name или имя последовательность символов, выделенная пробелами text или текст последовательность символов, выделенная не пробелами
После слова "текст" ставьте требуемый символ-ограничитель, типа: текст" или текст). - 295 -
ПРИМЕРЫ ХОРОШЕГО СТИЛЯ КОММЕНТИРОВАНИЯ.
Вот два примерных блока для иллюстрации хорошего стиля написания примечаний.
Блок # 126 0 \ Форматтер Структуры данных -- стр.2 06/06/83 1 6 CONSTANT TMARGIN \ #строки начала тела текста 2 55 CONSTANT BMARGIN \ #строки конца тела текста 3 4 CREATE HEADER 82 ALLOT 5 \ { 1счет-слева | 1счет-справа | 80заголовок } 6 CREATE FOOTER 82 ALLOT 7 \ { 1счет-слева | 1счет-справа | 80подпись } 8 9 VARIABLE ACROSS \ текущ. горизонтальная поз. форматтера 10 VARIABLE DOWNWARD \ текущ. вертикальная поз. форматтера 11 VARIABLE LEFT \ текущ. начальная левая граница 12 VARIABLE WALL \ текущ. начальная правая граница 13 VARIABLE WALL-WAS \ WALL при нач. форматирования тек. стр. 14 15
Блок # 127 0 \ Форматтер позицирование -- стр.1 06/06/83 1 : SKIP ( n) ACROSS + ; 2 : NEWLEFT \ сбросить левую границу 3 LEFT @ PERMANENT @ + TEMPORARY @ + ACROSS ! ; 4 : \LINE \ начать новую строку 5 DOOR CR' 1 DOWNWARD +! NEWLEFT WALL @ WALL-WAS ! ; 6 : AT-TOP? ( -- t=наверху) TMARGIN DOWNWARD @ = ; 7 : >TMARGIN \ переместиться от crease до TMARGIN 8 0 DOWNWARD ! BEGIN \LINE AT-TOP? UNTIL ; 9 10 11 12 13 14 15 - 296 -
СОГЛАШЕНИЯ ПО ФОРМИРОВАНИЮ ИМЕН.
Значение Форма Пример -------------------------------------------------------------
Арифметика ~~~~~~~~~~ целое 1 1имя 1+ целое 2 2имя 2* берет родственные входные параметры +имя +DRAW берет масштабирующие входные параметры *имя *DRAW
Компиляция ~~~~~~~~~~ начало "высокоуровневого" кода имя: CASE: конец "высокоуровневого" кода ;имя ;CODE добавить что-либо в словарь имя, C, исполняется при компиляции [имя] [COMPILE] несколько отлично имя' (штрих) CR' внутреннее представление или примитив (имя) или (TYPE)
часть периода исполнения компилирующего слова: где есть строчные буквы строчными if где нет строчных букв (ИМЯ) (IF) определяющее слово :имя :COLOR номер блока с оверлеем имяING DISKING
Структуры данных ~~~~~~~~~~~~~~~~ таблица или массив имена ЗАНЯТЫЕ общее число элементов #имя #ЗАНЯТЫХ текущий номер (переменная) имя# ЗАНЯТЫЙ# установить текущий номер ( n) имя 13 ЗАНЯТЫЙ переход на следующий элемент +имя +ЗАНЯТЫЙ размер смещения до записи от начала структуры имя+ ДАТА+ размер (в байтах) (сокращение от БАЙТОВ/имя) /имя /ЗАНЯТОГО указатель счетчика (индекс) >имя >IN перевести адрес структуры в адрес поля (записи) >имя >BODY - 297 -
Значение Форма Пример -------------------------------------------------------------
индекс в файле (имя) (ЛЮДИ) указатель в файле -имя -РАБОТА инициализировать структуру 0имя 0ЗАПИСЬ
Направление, Преобразование ~~~~~~~~~~~~~~~~~~~~~~~~~~~ назад имя< СМЕСТИТЬ< вперед имя> CMOVE>
от имя >TAPE преобразовать в имя>имя ФУТЫ>МЕТРЫ вниз \имя \LINE вверх /имя /LINE открыть {имя {FILE закрыть }имя }FILE
Логика, Управление ~~~~~~~~~~~~~~~~~~ вернуть булевский флаг имя? КОРОТКИЙ? вернуть обратный флаг -имя? -КОРОТКИЙ? адрес булевского значения 'имя? 'КОРОТКИЙ? работает условно ?имя ?DUP (быть может, DUP) включить +имя +ЧАСЫ или отсутствие символа имя МИГАНИЕ выключить -имя -МИГАНИЕ
Память ~~~~~~ сохранить значение @имя @КУРСОР восстановить значение !имя !КУРСОР записать в имя! СЕКУНДЫ! считать из имя@ СЧЕТЧИК@ имя буфера |имя |ВСТАВКИ адрес имени 'имя 'S адрес указателя на имя 'имя 'TYPE обменять, особенно байты >имя< >MOVE<
Числовые типы ~~~~~~~~~~~~~ длиной в байт Cимя C@ длиной 2 ячейки в двоичном дополнительном целом коде Dимя D+ смешанное 16 и 32-х разрядное Mимя M* длиной 3 ячейки Tимя T* длиной 4 ячейки Qимя Q* беззнаковая кодировка Uимя U. - 298 -
Значение Форма Пример -------------------------------------------------------------
Вывод, Печать ~~~~~~~~~~~~~ напечатать .имя .S напечатать численно (имя подчеркивает тип) имя. D. U. напечатать выровненным справа имя.R U.R
Количество ~~~~~~~~~~ "на" /имя /SIDE
Последовательности ~~~~~~~~~~~~~~~~~~ начало #>
Текст ~~~~~ следует строка, ограниченная " имя" ABORT" текст" текстовый или строковый оператор (в Бейсике -$) "имя "СРАВНИТЬ массив суперстрок (superstring array) "имя" "ЦВЕТА" - 299 -
КАК ПРОИЗНОСИТЬ СИМВОЛЫ.
! store - записать, загрузить @ fetch - разыменовать, взять, достать # sharp, number - диез (или "число", "номер") $ dollar - рубль % percent - процент ^ caret - шапка, не & ampersand - амперсанд, и * star - звездочка ( left paren - левая скобка ) right paren - правая скобка - dash - прочерк, минус, не + plus - плюс = equals - равно {} faces, curly brackets - фигурные скобки [] square brackets - квадратные скобки " quote - кавычка ' tick, prime - штрих ~ tilde - тильда | bar - вертикальная черта \ backslash - обратный слеш (также "под", "вниз" и "пропустить") / slash - слеш (также "вверх") < less-then, left-dart - меньше чем, левая угловая скобка > greater-then, right-dart - больше чем, правая угловая скобка ? question, query - вопрос, запрос , comma - запятая . dot - точка
