howprogrammingworks / book

Metaprogramming. Multi-paradigm approach in the Software Engineering.

Metaprogramming

Multi-paradigm approach in the Software Engineering

Index EN | Оглавление RU | Зміст UK | Obsah CZ

Generated books are located in /release folder

To build pdf file run:

npm i
npm run build

book's Issues

Глава 2-3-Context.md. Определение для Lexical environment не соответствует спецификации

Определение части спецификации Lexical environment:

Лексический контекст (Lexical environment) — набор
идентификаторов, связанных с определенными
значениями в рамках функции или блока кода (в том
числе блоков циклов, условий и т.д.).

было упразднено в пользу 9.1 Environment Records

Аналогично:
Объектный контекст функции стал Object Environment Records
Глобальный контекст стал Global Environment Records

Add spell check

It would be great if we could have some sort of spell check for md files. I suggest using yaspeller. It supports en/ru languages

Fix or split sentence

Initial report is here #101 (review)

Translate content into Czech

It would be great to develop a book also for Czechoslovakia:

• prepare file structure
• add Czech texts
• include new files to build

Понятие алгоритма

В главе 1-4 вводится однозначное определение алгоритма, что некорректно с точки зрения существования теории вычислимости. Более того, введенное здесь понятие алгоритма применимо только к императивному программированию, что понятно по наличию в определении слова "порядок вычислений" (в, например, функциональном программировании ни о каком порядке вычислений речи идти не может)
Подтверждение можно найти, например, в книгах А.В. Столярова - Том 1. Азы программирования (конкретную часть текста приложить не могу в связи с лицензией книги).

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

Глава: 2-6-Function.md. Неоднозначная семантика терминов: колбек. фабрика функций, функция-обертка, фабрики классов и прототипов соответственно

1. Если функция передается в другую функцию в качестве
   аргумента, то это колбек.
2. Если функция фозвращается в качестве результата, то это
   фабрика функций на замыканиях.
3. Если возвращаемая функция имеет ту же семантику, что и
   получаемая в аргументах, но с дополнительным (расширенным)
   поведением, то это функция-обертка.
4. Редко бывает, что возвращаемая функция не связана с функцией
   из аргументов, или связана не прямо, а также имеет другую
   семантику и функцией-оберткой она не является.
5. Если на выходе класс или функция-конструктор, то это фабрики
   классов и прототипов соответственно.
   Функция-обертка (Wrapper)

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

Фактически, все заявленные термины являются типичной композицией функций.

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

Links to book's index are broken

Describe the bug
Both links in the repository's README.md file that should navigate user to a book's index are broken.

Expected alternatives
Update links to a valid one from (i.e. for English Book/content/en/Index.md)

Screenshots
N/A

Add references
N/A

Multilingual builds for individual PDFs

Add new functionality and structures to create a book in EN / RU versions.

Rename book

Current: Multi-paradigm and Meta-programming in the Software Engineering

Proposed:

• Metaprogramming
• Multi-paradigm programming
• Metaprogramming and Multi-paradigm programming

Add subtitle:

• approach in the Software Engineering, etc.

Render lists to PDF

Try to render it like github do that. Here is an example in this chapter: https://github.com/HowProgrammingWorks/Book/blob/master/content/ru/2-1-Identifiers.md

Глава: 2-2-Types.md. Не полное, или противоречащее спецификации определение: Для JavaScript это [ссылка] подтипы Object, Function, Array.

Ссылка (Reference) указывает на значение ссылочного типа, т.е. не скалярное значение.
Для JavaScript это подтипы Object, Function, Array.

В JavaScript все идентификаторы являются ссылками Reference.
Если говорить в рамках терминологии книги, то В JavaScript не существует механизмов, которые бы адресовали и тем более возвращали скалярные типы.
Это подтверждается как официальной спецификацией,
так и архитектурой языка, в котором все Primitive Value имутабельны.
В следствии чего, конструкции вида:

var param1=1.2;
var param2=1.2;

приводят к созданию двух идентификаторов содержащих одну и туже ссылку, ведущую на структуру данных описывающих Primitive Value 1.2. Что совершенно логично, по причине того, что нет никакого смысла множить Primitive Value в условиях, когда их невозможно изменить в силу архитектуры языка.

Пруфы:

• ECMAScript® 2023 Language 13.1 Identifiers
• ECMAScript® 2023 Language 13.1.3 Runtime Semantics: Evaluation
• ECMAScript® 2023 Language Specification 9.4.2 ResolveBinding
• ECMAScript® 2023 Language Specification 9.1.2.1 GetIdentifierReference
• ECMAScript® 2023 Language Specification 6.2.4 The Reference Record Specification Type
• ECMAScript® 2023 Language Specification 6.2.4.5 GetValue ( V )
• ECMAScript® 2023 Language 6.2.4.6 PutValue ( V, W )

Sync 2-1 from ru to uk

Here is latest update of 2-1 section:

Book/content/ru/2-1-Identifiers.md

Lines 7 to 27 in 83b7b4a

	Есть разные конвенции (договоренности) о именовании, традиции языков и парадигм, но во всех них имена должны быть _консистентные_ (однотипные) и _понятные_ даже для тех, кто код этот не писал. Примеры хороших имен идентификаторов:
	- Глобальные переменные: `MAX_PURCHASE`, `REQUEST_TIMEOUT`, `ERROR_CODES`
	- Коллекции: `prices`, `goods`, `boughtItems`
	- Отдельные значения: `amount`, `groupName`, `total`
	- Функции: `calculateSubtotal`, `calculateTotal`, `validateExpenses`
	Примеры плохих имен рассмотрим подробнее:
	- Глобальная константа `Maximum` - не понятно, максимум чего, без второго слова константа не может быть глобальной; нарушены конвенции использования строчных и заглавных букв, вместо `camelCase` тут использован `PascalCase` и такую константу сложно заметить при чтении кода;
	- Таймаут запросов `request_timeout` - нарушены конвенции;
	- Коды ошибок `ERCODE` - сложно читается; не понятно, что это коллекция кодов, а не один код;
	- Массив цен `numbers` - не нужно называть массивы именами типов данных, которые в них находятся, из этого названия очень сложно понять, что там цены;
	- Массив товаров `arrayOfGoods` - не добавляйте названия структур данных в имена переменных;
	- Слишком длинное имя для коллекции товаров: `orderItemsInShopBasket`;
	- Неочевидное сокращение `amt`;
	- Кроме явного нарушения концепций `grp_N` еще и вводит в заблуждение, это плохое сокращение, не нужно экономить на буквах до такой степени;
	- Не называйте переменные транслитом, как `itogo2` и не используйте цифры для именования переменных с похожим смыслом, попробуйте учесть оттенки смысла, например: `total` и `subtotal`;
	- Если структура содержит два значения, как `tolalAndSubtotal`, то нужно назвать ее таким словом, которое обобщает их, например `order`;
	- Кроме нарушения конвенций `BuyerCalculations` еще и очень не точный, не понятно, какие именно вычисления;
	- Короткие сокращения типа `VE` - совершенно неприемлимы в качестве имен, если только это не общепринятые `i` и `j` для циклов или, `x` и `y` для координат и еще несколько подобных случаев.

Refactoring build file

The build file needs a little code correction and I already propose to display the long name of the book in two lines (title + subtitle) with probably different font styles (in future).

Глава 1-Introduction.md. Утверждение "физическая реализация вычислительной техники и природа человеческого мышления предполагают пошаговость" не отвечает действительности.

Abstarct

Фраза

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

Содержит как информацию не отвечающую действительности так и информацию, истинность которой, невозможно установить в рамках текущего уровня развития фундаментальной науки.

Информация, которая не отвечает действительности

но физическая реализация вычислительной техники [...] предполагают пошаговость.

В настоящее время, существуют архитектуры вычислительных машин принцип работы которых не детерменирован.
Это такие машины как:

• Квантовый компьютер;
• Днк компьютер;
• Биокомпьютер,
• ЭВМ на базе нечеткой логики,
• любые системы со слабым искусственным интеллектом.

Предлагаемое исправление

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

Информация, истинность которой не представляется возможности установить:

природа человеческого мышления предполагают пошаговость.

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

• Дефолт система мозга
• Зеркальные нейроны,
• Эксплицитная память
• и многое другое,

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

Main page (change style & text)

1. I propose to center the content of the main page (for beauty). It will also improve the design of the Russian version. At the moment, the long RU-subtitle is partially wrapped on a new line (it breaks), and the main title does not fit at all (it is necessary to reduce the font size).
2. Remove "Copyright" before the author's name (because not necessary).
3. Replace "HowProgrammingWorks" with "Metarhia" (because clearer and appercases in Russian look so-so).

For example, "Metarhia contributors", or better - "Metarhia community"

Глава 1-Introduction.md. Утверждение "а искусство, потому, что ... вынуждено прибегать к интуиции и слабо осмысленному личному опыту" может вызвать не нужные ассоцииации.

Фраза

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

Describe the bug

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

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

Разумеется, редакторы перевода это еще не автор, к счастью не составило большого труда узнать, что же сам автор думает об искусстве буквально в его собственном предисловии первым предложением идет фраза:

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

или в оригинале:

THE PROCESS of preparing programs for a digital computer is especially attractive, not only because it can be economically and scientifically rewarding, but also because it can be an aesthetic experience much like composing poetry or music

Более того, следующие две фразы самого Тимура, на мой взгляд как раз таки описывают сущность данного искусства:

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

Expected alternatives

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

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

Послесловие:

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

Возможно, у кого-то возникнет вопрос почему я привел цитаты из книги Дональда Кнута, ведь это совсем другая книга и даже не ее перевод, мой ответ в том, что именно он, по моему мнению, первый кто связал эти два слова (программирование и искусство) в одно самостоятельное понятие.

Incorrect display of italic text in pdf version

In section 2.1 of Metaprogramming-ru.pdf you can find word _имена_, while in md version its written in italic.

I suppose it's a wrong conversion and same thing happens in other pdf files too.

Fix punctuatio

Several text files have many punctuation errors and other linguistic problems:

• ru/1-1-Approach.md

• ru/1-2-Examples.md

• ru/1-3-Modeling.md

• ru/1-4-Program.md

• ru/1-6-Engineer.md

• ru/1-7-Paradigms.md

I'll try to solve them at least partially.

Try to avoid examples duplication

Now we have duplicated examples for all natural languages

Глава: 2-6-Function.md. Термины Superposition и Composition говорят об одном и том же

Термин Superposition является синонимом к термину Composition

Термин Superposition является архаизмом и давно вытеснено термином Composition (Композиция) или Function composition (Композиция функций). Насколько мне известно, употребления термина суперпозиции в плоскости программирования, свойственно было только русскоязычной части интернета и никогда не употреблялась в зарубженой литературе, где существовал только термин Function composition