Forth и другие саморасширяющиеся системы программирования Locations of visitors to this page
Текущее время: Пт ноя 24, 2017 17:01

...
Google Search
Forth-FAQ Spy Grafic

Часовой пояс: UTC + 3 часа [ Летнее время ]




Начать новую тему Ответить на тему  [ 1 сообщение ] 
Автор Сообщение
 Заголовок сообщения: соглашения по оформлению кода.
СообщениеДобавлено: Чт июн 25, 2015 16:00 
Не в сети
Moderator
Moderator
Аватара пользователя

Зарегистрирован: Чт май 04, 2006 00:53
Сообщения: 4831
Откуда: был Крым, теперь Новосибирск
Благодарил (а): 18 раз.
Поблагодарили: 52 раз.
содержимое файла agreements.txt
Код:
                              Общие параметры.

     Ширина  экрана  не  превышает 80 символов - текст не должен выходить за
его  пределы.  Весь  текст набирается в ДОС кодировке (CP866). Слова базовой
системы  набираются  в  верхнем  регистре,  дополнительные слова, реализация
которых  может  меняться,  а так же  слова,  которые нельзя использовать - в
нижнем  регистре  либо  вРазБрос.  Прототипы  слов,  то есть слова,  которые
никогда (либо очень редко)  не вызываются  по-имени,  заключаются  в круглые
скобки.

                                 Заголовок.

В начале подключаемого файла находится заголовок:
- в  самой  первой  строке  - дата создания файла, ссылка на НИК создавшего
   этот файл. Код может не принадлежать указанному человеку, но сгруппировал
   его  тот,  чей  ник  в  начале  файла  (то есть я в большинстве случаев).
- во  второй  строчке  копирайт - права принадлежат тому, чей код находится
   в  данном  файле.  Свой  копирайт я ставлю, только если от старого текста
   не  осталось  ни  строчки.  Каждое  слово, которое я переделал или ввел в
   сборку  отмечается символом '√' - соответственно, если все слова помечены
   данным символом я меняю копирайт (а символ √ убираю).
- в  третьей  и   последующих  строках  идет  описание  содержимого  файла.

   В заголовке не должно  быть  более  пяти  строк.  При необходимости более
подробного  описания  текста файла, само описание выносится в конец файла за
слово \EOF . Пример заголовка находится в начале данного текста.


                      Переключение системы счисления.

     Основная  система   счисления  десятичная. Слова переключения основания
системы  выравниваются  по  центру  экрана  (HEX  DECIMAL). Где только можно
используется  0xABC  формат представления  шестнадцатеричных чисел. То есть,
нигде  в  исходных  текстах  переменная  BASE  не  меняется, а все числа без
префикса представлены в десятичной системе.


                                Комментарии.

Используется три вида комментариев:
- комментарий до конца текста: Все после слова '\EOF' до конца файла;
- комментарий до конца строки: после слова '\ ' до конца строки;
- скобочный комментарий: начинается словом '( ' заканчивается словом ) .

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

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

     Скобочный комментарий  используется  для отображения стековых диаграмм.
Наличие  стековых диаграмм обязательно для любых слов, создающих заголовки в
целевом  словаре.  Стековая диаграмма обычно выглядит следующим образом:
  ( состояние стека до исполнения слова --> состояние стека после ) .
В  случае  описания  работы  компилирующих  слов,  к  примеру WHILE стековый
коментарий  относится  ко  времени  исполнения  скомпилированного кода, а не
ко времени создания!  Альтернативный  вариант стекового коментария для слов,
компилирующих код в определения следующий:
( стек в режиме компиляции \\ режиме исполнения скомпилированного кода )
например: LITERAL ( n --> \\ --> n )

     Для  описания  используемых  словом параметров используются сокращения,
перечисленные  в  .\_\abbreviations. Использование круглых скобок для других
видов  комментариев  запрещено.  Стековый  комментарий начинается либо сразу
после   имени   слова  (если  начато  двоеточное  определение),  либо  после
перечисления  необходимых  параметров  в  той  же  строке, где создается имя
слова.  Внутри  стекового  комментария  возможно описание выполняемой словом
функции,  например ( n --> n+4 ) для слова CELL+. Если слово берет что-то из
входного  потока то это отображается в комментарии после символа '/' пример:
(  n  /  name  --> ). Для отображения вариантов принимаемых или возвращаемых
значений  используется  символ '|' : ( a b c --> n true | false ). Изменение
на  стеке  возвратов тоже отображается с помощью идентификатора r:
: RDROP ( r:  n  --> ),
изменения  на  стеке  данных  по  умолчанию  никак  не  выделяются,  но  при
использовании  r:  изменения  на  стеке  данных  идентифицируются по символу
d: , например: : R+ ( d: a r: b --> r: a+b ) ... ; внутри стековой диаграммы
допускается  отображение действий, производимых над входными данными, как на
примере выше.
     Внутри слова может быть только один стековый комментарий. Это связано с
тем,  что  стековые  комментарии  автоматически выдираются для сохранения их
содержимого  в  файле  отчета  .  \names.xrf,  поэтому в стековом коментарии
отображаются   параметры   соответствующие   выполнению   слова  (или  кода,
скомпилированного  этим  словом ). Содержание,  заключенное  внутри  круглых
скобок не анализируется, поэтому может быть произвольным.


                                Именование слов

Слова именуются латинскими буквами. Длина имен слов не ограничена ничем,  но
с рациональных соображений длина имени слова не должна превышать 1\3 экрана,
то есть, желательно, не более  26 символов (обычно более длинные имена - это
имена  импортируемых  API  функций).  Все  имена  регистрозависимы, поэтому,
например,  DUP dup Dup  и прочие  варианты  - это  разные  слова.  В  именах
используются  принятые  сокращения,  описанные в abbreviations.txt, а так же
следующие правила:
1. имена в квадратных скобках, к примеру [IF], имеют признак IMMEDIATE
   и вмешиваются в работу парсера, например забирают лексемы из входного
   потока: [CHAR] A .
2. Имена в круглых скобках не предназначены для прямого вызова, и обычно
   используются из VECT и USER-VECT переменных, поэтому при попытке
   исполнения таких слов, может лишь возвращаться адрес исполнимого кода.
3. вопросительный знак в начале имени предполагает, что определение само
   что-то проверяет, либо требует на входе флаг: ?COMP ?IMMEDIATE и пр.
4. Слова набранные ЗАГЛАВНЫМИ буквами являются системными, и скорее всего в
   ядре не будут изменяться (вобщем не обязательное правило).
5. Слова, начинающиеся с 'off_' являются частью структур.
6. Часто слова начинающиеся с литеры 'N' : N?BRANCH NABORT" NDEFINE и
   подобные им обозначают выполнение действия по FALSE.
7. символ 'U' в начале имени говорит о том, что слово работает с беззнаковым
   числом(ами), например: U< UMAX UD/
8. символ 'S' в начале имени говорит о том, что слово работает с знаковым
   числом (числами): S>D SD* ; либо со строкой: S" SLITERAL S:
9. символ 'D' в имени говорит о том, что имя работает с числами двойной
   длины: S>D DS/ SD* D>R D>L DDROP и подобные им слова.
A. символы:  ':'  и  ';'  в имени определения говорят о том, что определение
   создает (в  случае  двоеточия),  либо  завершает,  либо  компилирует EXIT
   в случае ';'. Например:  S: - создает новое определение,  а  ;THEN  ;ELSE
   компилируют EXIT в код текущего определения.

                  Оформление высокоуровневых определений.

        Написание каждого слова начинается с комментария:

\ комментарий перед словом должен отвечать на вопрос "что делает слово"
: Пример ( стековая --> диаграмма ) если код вмещается в одну строку ;

комментарий располагается  перед  началом  определения  и не должен занимать
более  трех  строчек  текста.  Стековая  диаграмма находится сразу за именем
слова. Если код слова вмещается в одну строку сразу за стековым комментарием
то он не переносится на следующую строку (как в примере выше).

\ пример многострочного определения
: ИмяСлова ( a / name --> b true | false )
           если код слова не вмещается на одну строку вместе с коментарием
           то он переносится на следующую строку, и начинается под стековой
           диаграммой,
           с этой же позиции начинается каждая новая строка ;

\ пример комментирования кода
: EXCHANGE ( a addr --> b )
           DUP @            \ --> a addr [addr]
           -ROT ! ;         \ сохранили новое значение

\ пример выделения структур управления
: (prompt) ( --> )
           STATE @ IF ." ]"     \ если ветвления не вмещаются на одну
                    ELSE CR     \ строку то отступ ELSE на одну позицию
                         ." >"  \ от IF, код после ELSE равняется
                   THEN ;       \ THEN возвращает отступ на место.

\ пример выделения циклов
: ( ( --> )
    BEGIN NEXT-WORD DUP WHILE           \ условие выхода - последнее слово
          + char - C@ [CHAR] ) <> WHILE \ в строке

      REPEAT EXIT               \ в зависимости от варианта использования
    THEN 2DROP                  \ REPPEAT либо возвращает отступ до уровня
    ; IMMEDIATE                 \ BEGIN либо не доходит до него две позиции.

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

_________________
Мне бы только мой крошечный вклад внести,
За короткую жизнь сплести
Хотя бы ниточку шёлка.
fleur


Вернуться к началу
 Профиль Отправить личное сообщение  
Ответить с цитатой  
Показать сообщения за:  Поле сортировки  
Начать новую тему Ответить на тему  [ 1 сообщение ] 

Часовой пояс: UTC + 3 часа [ Летнее время ]


Кто сейчас на конференции

Сейчас этот форум просматривают: Majestic-12 [Bot] и гости: 1


Вы не можете начинать темы
Вы можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете добавлять вложения

Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group
phpBB сборка от FladeX // Русская поддержка phpBB