Способ мышления-Форт



Глава 5. Разработка: элементы Форт-стиля - часть 23


Пример:

: IF ( ? -- ) ... \ Компиляция: ( -- адр-неразрешенной-ссылки) ... ; IMMEDIATE

В компилирующих словах первая строка комментария описывает поведение в режиме исполнения, которое обычно и является `синтаксисом при использовании` слова. Второй комментарий описывает, что слово `в действительности делает` при компиляции (что менее важно для пользователя).

Еще примеры:

: ABORT" ( ? -- ) \ Компиляция: текст" ( -- )

Иногда компилирующее слово может по-другому вести себя при вызове `вне` определения через двоеточие. Такие слова (они вызывают брезгливость) требуют три строки комментария.

К примеру:

: ASCII ( -- c) \ Компиляция: с ( -- ) \ Интерпретация: с ( -- с ) ... ; IMMEDIATE

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

ВЕРТИКАЛЬНЫЙ ФОРМАТ ЗАПИСИ ПРОТИВ ГОРИЗОНТАЛЬНОГО.

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

Кто будет читать мой код?

Насколько удобочитаемы мои определения?

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

\ КЦК Контрольная сумма 07/15/83 : НАКОПИТЬ ( старКЦК символ -- новКЦК ) 256 * \ сдвинуть символ в старший байт XOR \ и искл.-ИЛИ со старым КЦК 8 0 DO \ затем восемь раз DUP 0< IF \ если старший бит равен "1" 16386 XOR \ искл.-ИЛИ с маской DUP + \ и сдвинуть влево на 1 разряд 1+ \ установить "1" в младшем бите ELSE \ иначе, т.е. если старший бит - "0" DUP + \ сдинуть влево на 1 разряд THEN \ LOOP ; \ завершение цикла

При другом подходе кодовые фразы не перемежаются повествовательными комментариями.


Содержание  Назад  Вперед