OberonCore
https://forum.oberoncore.ru/

Немножко подокументировал компилятор
https://forum.oberoncore.ru/viewtopic.php?f=28&t=6287
Страница 1 из 4

Автор:  budden [ Суббота, 06 Октябрь, 2018 22:06 ]
Заголовок сообщения:  Немножко подокументировал компилятор

За основу взята http://obertone.ru/_media/bb/op2.paper.pdf, ну и в код тоже заглядывал.

Чтобы было ясно, некоторые соглашения, которые я применяю:

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

- в неочевидных местах латиница подчёркнута

- шрифтами я не заморачивался

Конструктивная критика приветствуется. Если есть желающие продолжить и углубить, есть небольшое финансирование - пишите в личку.

Изменённые файлы можно увидеть в моём репозитории (см. историю изменений):

https://bitbucket.org/budden/blackboxco ... er/commits

У меня нет цели создать исчерпывающую документацию. Я лишь намечаю вехи, чтобы было легче разбираться, причём не во всех аспектах работы компилятора, а только в тех, которые мне нужны для моих текущих целей. Пока писал - многое понял. И ещё - тот документ написан про другой компилятор. Я в целом не проверял достоверность информации, приведённой в ОП2, применимо к BlackBoxComponentBuilder, но лишь заменял имена.

Автор:  budden [ Пятница, 12 Октябрь, 2018 14:27 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Сделал ещё несколько документов (там пока очень мало). Их можно скачать здесь:

https://bitbucket.org/budden/blackboxco ... v/Docu/ru/

И пришёл к выводу, что так неудобно. Обсудили с Иваном, пока по результатам созрела такая идея.
Перед каждой процедурой вставляется комментарий вида
Код:
(***
Подробное описание процедуры с возможными ссылками вида модуль.имя на другие процедуры
*)
PROCEDURE Блабла(*КраткоеРусскоеИмя*)*


И далее везде заменяем Блабла на Блабла(*КраткоеРусскоеИмя*)
Такое преобразование обратимо, совместимо с изменениями в коде компилятора, не меняет интерфейс и т.п. Будет, правда, проблема с одноимёнными полями в разных структурах. Если у них разный смысл - можно промахнуться и переименовать неправильно. Но это придётся потерпеть - на функционировании программы оно сказаться не должно.

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

Автор:  Иван Денисов [ Пятница, 12 Октябрь, 2018 15:45 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Я думаю, что надо делать документацию в виде документации и переименовывать в переменные на английском, но при этом "говорящие". Комментарии в коде не заменят "энциклопедию" по компилятору.

Автор:  budden [ Пятница, 12 Октябрь, 2018 15:52 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Да, я пришёл к тому, чтобы переименовывать, но сразу в русские. Компиляторов полно, а много ли компиляторов на русском языке? Ноль. Во всяком случае, из известных мне. Будет сразу учебный компилятор. Документацию можно будет сделать потом и она будет на концептуальном уровне. Но здесь я вижу основной подход "снизу вверх", поэтому начинать нужно с отдельных функций. А не бросите ли ссылкой на "Петра творенье" с выводом АСТ? Я как раз думал делать такую утилиту, потому что она нужна для отладки и понимания происходящего.

Автор:  Иван Денисов [ Пятница, 12 Октябрь, 2018 17:53 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Я не помню точно, где это лежит, но Пётр тут бывает на форуме.
Где-то наверное должно быть у него в репе:
https://bitbucket.org/petryxa/

Автор:  budden [ Понедельник, 15 Октябрь, 2018 03:37 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Нашёл вот что https://github.com/kpmy/xev - это оно?

Автор:  budden [ Вторник, 30 Октябрь, 2018 00:51 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Сегодня разобрался (в общих чертах) в работе функции SYSTEM.VAL.

https://gitlab.com/budden/nkp/commit/9c ... 5c80553e2b

Оказывается, необязательно ломать компилятор КП. Вполне можно строить рядом свой, соседний.

Автор:  prospero78 [ Вторник, 30 Октябрь, 2018 11:02 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

budden писал(а):
Оказывается, необязательно ломать компилятор КП. Вполне можно строить рядом свой, соседний.

Более того: это единственно верный путь.

Автор:  budden [ Среда, 31 Октябрь, 2018 16:18 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Да нет, не единственный, но позволяющий наиболее быстро увидеть какой-то результат.

С высоты самолёта разобрался в файлах символов и импорте их по директиве IMPORT.
Обновил общее описание http://программирование-по-русски.рф/static/док-ня.html

Коммит здесь:
https://gitlab.com/budden/nkp/commit/52 ... 8d3fd65f2c

Автор:  Иван Денисов [ Среда, 31 Октябрь, 2018 16:21 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

На мой взгляд, сокращения не дают понятного кода и документации.
Например почему не назвать НяП = КомпиляторПарсер
Тогда и код будет читаться потом легко.

Автор:  budden [ Среда, 31 Октябрь, 2018 16:56 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Зависит от конкретного файла. Из соображений сжатия информации, часто встречаемые слова должны быть короткими, а редко встречаемые - длинными. Например, «я», «ты», «и», «три», «бей», «дичь» - это короткие слова (для некоторых ещё важна скорость произнесения), а вот слово «тиранозавр» - длинное, хотя он тоже - дичь. НяФС встречается в исходниках ББ (в том, что от них осталось у нас) 1100 раз, НяМ - 830 раз, RECORD - 2900 раз. НяП - всего 10 раз. НяКомпилятор - 7, Г468Ну - 920 раз. Соответственно, НяП следует переименовать в НяПарсер, а НяФс, НяМ и НяГ486Ну нужно оставить как есть. Хотя есть псевдонимы при импорте... Но они всё же усложняют понимание.

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

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

Ах, VS Code опять подлянку подложил. Поиск по словам для русского языка не работает. Уже начинаю подумывать о том, чтобы разморозить свою IDE. В ней и работа с окнами более толково устроена, и поиск лучше организован. И нет опоры на проклятые регулярные выражения. И нет слоя локализации - текст сообщений забит прямо в исходнике - это существенно облегчает работу с текстом.

Т.е. эти цифры нужно воспринимать осторожно... Но думаю, в целом похоже на правду.

Автор:  prospero78 [ Среда, 31 Октябрь, 2018 18:50 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Цитата:
Из соображений сжатия информации, часто встречаемые слова должны быть короткими, а редко встречаемые - длинными.

Вот я против. Я называю POINTER TO RECORD в виде tpBoxLinear и туЯчейкаЛин -- т. е. откровенно короткие только префиксы, а содержательная часть должна быть достаточной для понимания, даже без словаря в голове по часто употребимым словам.
Код должен читаться как текст (с).

Автор:  budden [ Среда, 31 Октябрь, 2018 20:13 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Проще запомнить часто встречаемое слово, чем каждый раз читать все его многочисленные буквы.

То, что встречается через строку, должно быть коротким. Иначе оно загромоздит текст и он не будет понятен по той причине, что у человека ограниченное поле зрения. И оно может позволить себе быть коротким, т.к. даже если оно непонятно, его посмотришь 10 раз, на 11-й запомнишь, и постоянное его повторение не даст его забыть.

На случай, если конкретная аббревиатура непонятна, должны быть докстринги, которые показываются по hover или при установке курсора клавиатуры на это слово. Или должен быть переход к определению за одно нажатие из любого контекста (синтаксис КП это прекрасно позволяет, просто это никто за 30 лет не удосужился воплотить почему-то). Т.е. здесь мы сталкиваемся опять же с тем, что среда ББЦБ слишком аскетична и не позволяет никаким путём добиться производительности труда. Этот вопрос можно решить, как в рамках ББЦБ, так и в рамках другой IDE. Пусть он сейчас пока не решён, я закладываюсь на то, что он будет решён.

А так - я не против говорящих имён. Например, InObj я переименовал в ЧитайОписаниеОбъектаИзСимвольногоФайлаВставьВОбластьИВерни_InObj, что даёт примерное представление о работе этой функции (хотя я не все ветви прочитал).

Чтобы эту дискуссию не развивать - вы имеете право на своё мнение. Но пока что здесь работаю над этим один я, а хозяин-барин. Станете акционером - сможете влиять на решения :)

Автор:  budden [ Среда, 31 Октябрь, 2018 22:48 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Переименовал НкП в НкПарсер. Остальные модули не буду (пока). На самом деле даже вариант с псевдонимом импорта
не даёт большой выгоды - помнить этот псевдоним придётся всё равно. В 1000 мест заменять короткое слово на длинное считаю неправильным. А значит - пусть остаётся короткое имя модуля и во второй строке модуля написано, о чём он.

И также переименовал qualident (уже не помню, во что :) )

Автор:  adva [ Четверг, 01 Ноябрь, 2018 09:39 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Я тоже за полное название без сокращений. Вроде как попадалось исследование, что слово читается не по буквам, а целиком. Не зря же, даже с перестановками букв слово воспринимается ничуть не хуже, чем правильно написанное. Чем держать в операционной (или как там она называется) памяти сокращения, быстрее прочитать полное слово. Хотя чересчур длинные тоже воспринимаются плохо (если это не процедура). Для работы в ББ из коробки минус только в том, что нет автодополнения, хотя допилить его вполне возможно, вроде у Петра были где-то наработки, я их сам пробовал использовать, но, к сожалению ничего не сохранилось.

Автор:  budden [ Четверг, 01 Ноябрь, 2018 11:28 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

Хорошо. Есть уже 4 человека, которые против моих соглашений об именах - три здесь и один здесь http://plana.mybb.ru/viewtopic.php?id=766 . Я на 100% уверен, что я принял все решения правильно, но я готов уступить. Для этого мне нужно из вас четырёх два добровольца, которые возьмут на себя конкретные обязательства по объёмам переводимого текста и срокам. Я даже не прошу автодополнение :)

Автор:  budden [ Четверг, 01 Ноябрь, 2018 11:53 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

А вот пример, чего стоят длинные имена:
Код:
 PROCEDURE qualident(VAR id: DevCPT.Object);
  VAR obj: DevCPT.Object; lev: BYTE;
 BEGIN (*sym = ident*)
  DevCPT.Find(DevCPS.name, obj); DevCPS.Get(sym);
  IF (sym = period) & (obj # NIL) & (obj.mode = Mod) THEN
   DevCPS.Get(sym);
   IF sym = ident THEN
    DevCPT.FindImport(DevCPS.name, obj, obj); DevCPS.Get(sym)
   ELSE err(ident); obj := NIL
   END
  END ;
  IF obj = NIL THEN err(0);
   obj := DevCPT.NewObj(); obj.mode := Var; obj.typ := DevCPT.undftyp; obj.adr := 0
  ...

Превратится в
Код:
 PROCEDURE РазбериВозможноКвалифицированныйИдентификатор(
   VAR id: КомпиляторФайлСимволов.Object);
  VAR obj: КомпиляторФайлСимволов.Object; lev: BYTE;
 BEGIN (*ТекущаяЛексема = ident*)
  КомпиляторФайлСимволов.Find(КомпиляторЛексер.name, obj);
  КомпиляторЛексер.Get(ТекущаяЛексема);
  IF (ТекущаяЛексема = period) & (obj # NIL)
    & (obj.КлассИдентификатора = КлассИдентификатораМодуль) THEN
   КомпиляторЛексер.Get(ТекущаяЛексема);
   IF ТекущаяЛексема = ident THEN
    КомпиляторФайлСимволов.FindImport(КомпиляторЛексер.name, obj, obj);
    КомпиляторЛексер.Get(ТекущаяЛексема)
   ELSE err(ident); obj := NIL
   END
  END ;
  IF obj = NIL THEN err(0);
   obj := КомпиляторФайлСимволов.NewObj();
   obj.КлассИдентификатора := Var;
   obj.typ := КомпиляторФайлСимволов.undftyp; obj.adr := 0
 ...

Видите, сколько раз повторяется здесь слово "Компилятор". А зачем? Мы же не идиоты и нам достаточно один раз
запомнить, что мы читаем исходник компилятора. Получается "масло масляное" и "вода водяная". Меня лично
такое постоянное мелькание одного длинного слова раздражает. И любому человеку оно объективно будет мешать
понять текст, потому что оно текст загромождает и смысловую составляющую текста нужно выискивать среди
повторений слова "Компилятор", как иголку в стоге сена.

А вот вариант с длинными именами всего, кроме модулей:
Код:
 PROCEDURE РазбериВозможноКвалифицированныйИдентификатор(VAR id: НяФс.Object);
  VAR obj: НяФс.Object; lev: BYTE;
 BEGIN (*ТекущаяЛексема = ident*)
  НяФс.Find(НяЛ.name, obj); НяЛ.Get(ТекущаяЛексема);
  IF (ТекущаяЛексема = period) & (obj # NIL)
    & (obj.КлассИдентификатора = КлассИдентификатораМодуль) THEN
   НяЛ.Get(ТекущаяЛексема);
   IF ТекущаяЛексема = ident THEN
    НяФс.FindImport(НяЛ.name, obj, obj); НяЛ.Get(ТекущаяЛексема)
   ELSE err(ident); obj := NIL
   END
  END ;
  IF obj = NIL THEN err(0);
   obj := НяФс.NewObj(); obj.КлассИдентификатора := Var;
   obj.typ := НяФс.undftyp; obj.adr := 0

Здесь явно напрашивается на сокращение ещё и ТекущаяЛексема. Сделать её какой-нибудь
ТекЛекс, и станет вот так:
Код:
 PROCEDURE РазбериВозможноКвалифицированныйИдентификатор(VAR id: НяФс.Object);
  VAR obj: НяФс.Object; lev: BYTE;
 BEGIN (*ТекЛекс = ident*)
  НяФс.Find(НяЛ.name, obj); НяЛ.Get(ТекЛекс);
  IF (ТекЛекс = period) & (obj # NIL)
    & (obj.КлассИдентификатора = КлассИдентификатораМодуль) THEN
   НяЛ.Get(ТекЛекс);
   IF ТекЛекс = ident THEN
    НяФс.FindImport(НяЛ.name, obj, obj); НяЛ.Get(ТекЛекс)
   ELSE err(ident); obj := NIL
   END
  END ;
  IF obj = NIL THEN err(0);
   obj := НяФс.NewObj(); obj.КлассИдентификатора := Var;
   obj.typ := НяФс.undftyp; obj.adr := 0

Текущая лексема проходит красной нитью через весь парсер, её проще один раз запомнить, чем каждый раз читать.

Автор:  budden [ Четверг, 01 Ноябрь, 2018 11:55 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

И здесь есть разница, она почти очевидна. Для человека, который видит текст впервые, длинная версия лучше. Для человека, который залез в этот текст и сидит в нём хотя бы пару дней, лучше короткая версия. А я ведь переименовываю не просто так, а с целью дальнейшей переработки компилятора. Как я уже сказал, я готов уступить, но при некоторых условиях, о которых я тоже сказал :)

Автор:  Kemet [ Четверг, 01 Ноябрь, 2018 13:08 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

нужно правильные имена давать, иначе дрянь получается

Автор:  Иван Денисов [ Четверг, 01 Ноябрь, 2018 14:21 ]
Заголовок сообщения:  Re: Немножко подокументировал компилятор

В чем проблема заменить КомпиляторЛексер на Лексер при импорте?

Страница 1 из 4 Часовой пояс: UTC + 3 часа
Powered by phpBB® Forum Software © phpBB Group
https://www.phpbb.com/