WIP

Author: tabuna

content/003-big.md

@@ -2,33 +2,39 @@
 
 После прочтения `README` в любом проекте возникает естественное желание оценить масштаб работы. 
 Насколько велика система? Насколько быстро я смогу в ней разобраться и начать вносить изменения?
+Эти вопросы важны не только для новичка, но и отражают уровень прозрачности архитектуры и зрелости проекта.
 
 Во многих экосистемах по умолчанию доминирует монолитный подход. 
-Это классика, проверенная временем. 
-Его используют:
+Это классика, проверенная временем.
+
+<div style="page-break-after: always;"></div>
 
+Его используют:
 - Laravel (PHP)
 - Django (Python)
 - Ruby on Rails (Ruby)
 - Phoenix Framework (Elixir)
 - Spring (Java)
 - Sails (Node.js)
 
-И этот список можно продолжать долго — монолиты надёжны, удобны и, что важно, имеют широкую поддержку в виде инструментов и сообществ. 
+И этот список можно продолжать долго — монолиты надёжны, удобны и, что важно, имеют широкую поддержку в виде
+инструментов и сообществ.
 Это безопасная отправная точка практически для любого проекта.
 
 Однако столкнуться с **20 000+** файлов и папок в репозитории — для любого разработчика может стать демотивирующим
 шоком.
 Это словно стоять перед огромным валуном и пытается его сдвинуть с места.
 
-Даже опытный разработчик теряет мотивацию, когда не видит четкой структуры, границ ответственности, понятных точек входа.
-Это не просто психологический барьер — это профессиональная фрустрация: ты не понимаешь, где начать, как не сломать, как внести изменения безопасно.
+Даже опытный разработчик теряет мотивацию, когда не видит четкой структуры, границ ответственности, понятных точек
+входа.
+Это не просто психологический барьер — это профессиональная фрустрация: ты не понимаешь, где начать, как не сломать, как
+внести изменения безопасно.
 
 В любой работе, будь то программный код, список дел или физическая работа — есть
 одно универсальное правило: разбивай большую задачу на маленькие части.
 
 Это вовсе не значит, что каждый монолит обязательно нужно дробить на десятки микросервисов. Нет, не стоит
-драматизировать. 
+драматизировать.
 Речь о том, что даже внутри монолита обязательно нужно выделять и изолировать компоненты, которые можно вынести в
 отдельные репозитории.
 
@@ -42,11 +48,11 @@ class Temperature
 }
 ```
 
-Этот компонент можно вынести в собственный репозиторий, покрыть тестами, 
+Этот компонент можно вынести в собственный репозиторий, покрыть тестами,
 добавить документацию и подключать через Composer как внешнюю зависимость.
 
-Такой подход упрощает основную кодовую базу и снижает когнитивную нагрузку: вместо тысячи связанных между собой файлов 
-разработчик имеет дело с чётко очерченным, изолированным модулем. 
+Такой подход упрощает основную кодовую базу и снижает когнитивную нагрузку: вместо тысячи связанных между собой файлов
+разработчик имеет дело с чётко очерченным, изолированным модулем.
 
 Кроме того, переиспользуемые и опубликованные компоненты не просто сокращают дублирование — они создают эффект "внешней
 границы", когда ответственность модуля очевидна и проверяется временем.
@@ -55,14 +61,13 @@ class Temperature
 «Да, я могу разобраться с этим и внести изменения», — а потом постепенно расширять понимание всего проекта и его частей.
 Это сильно снижает тревожность и прокрастинацию. Чем понятнее и локальнее задача — тем выше вовлечённость.
 
-
 Кроме того, отдельные небольшие пакеты часто можно и нужно выкладывать в open source — это не то, что подпадает под
 ограничения или коммерческую тайну. Это чистый, полезный, часто общепринятый код.
 
 Они могут стать отличным инструментом для профессионального роста и демонстрации своих навыков.
 
 Часто можно встретить талантливых разработчиков, которые годами работают внутри одной компании, в огромном монолите,
-но не могут продемонстрировать ни одной строчки своего кода. 
+но не могут продемонстрировать ни одной строчки своего кода.
 Почему? Потому что весь их труд спрятан за корпоративным VPN, внутри безликой и плохо структурированной массы.
 
 Поэтому небольшие компоненты и пакеты — это одновременно и технический, и карьерный инструмент, который стоит

content/007-naming.md

@@ -155,9 +155,7 @@ abstract class AbstractContextHandler
     ): array
     {
         return [
-            'encodedContextualPayloadFragment' => $this->map($contextBoundSemanticUnit),
-            'componentUnitIntegrityChecksum' => sha1(serialize($contextBoundSemanticUnit)),
-            'injectedContextualTagToken' => uniqid('module_ctx_unit_', true),
+            'encodedPayloadFragment' => $this->map($contextBoundSemanticUnit),
             'operationalModuleDomain' => $this->moduleNamespaceScopeIdentifier,
         ];
     }

content/008-mysterious-value.md

@@ -4,6 +4,8 @@
 Разработчик открывает IDE, запускает поиск по имени метода или класса, и — вперёд, прямо в код. 
 Только когда поведение становится неочевидным, когда логика не складывается — он обращается к документации, вики, базе знаний если такая вообще есть или еще хуже к коллеге выпрашивая информацию по чайной ложке.
 
+<div style="page-break-after: always;"></div>
+
 Рассмотрим классическую ситуацию:
 
 ```php

content/010-no-nonsense.md

@@ -201,6 +201,47 @@ $city = $user->address->city();
 > {notice} Паттерн `Null Object` полезен не только для возврата значений по умолчанию, но и для реализации методов, которые
 > не должны выполнять никаких действий.
 
+### Ссылки делают код хрупким
+
+Передавать переменную по ссылке кажется удобным: функция сразу меняет её — меньше кода, меньше присваиваний.
+Вот пример:
+
+```php
+// Плохо [✗]
+function celsiusToFahrenheit(float &$celsius): void
+{
+    $celsius = $celsius * 9 / 5 + 32;
+}
+
+$temp = 25;
+celsiusToFahrenheit($temp);
+echo $temp; // 77 — значение изменилось «внутри» функции
+```
+
+На первый взгляд это экономия кода, но есть подвох: после вызова функции уже не понятно, изменится переменная или нет.
+Изменения происходят «за кадром», что усложняет чтение и поддержку кода.
+
+Из-за этого код становится хрупким — любое забытое или неожиданное изменение может сломать логику программы.
+
+Лучшей практикой считается писать функции, которые принимают значение и возвращают новый результат, не изменяя исходные
+данные:
+
+```php
+// Хорошо [✓]
+function celsiusToFahrenheit(float $celsius): float
+{
+    return $celsius * 9 / 5 + 32;
+}
+
+
+$temp = 25;
+$tempInFahrenheit = celsiusToFahrenheit($temp);
+echo $temp; // 25 — значение не изменилось
+```
+
+Такой код прозрачный и предсказуемый: переменные не меняются «вдруг», а результат возвращается явно и используется там,
+где нужно.
+
 ### Место для расширения
 
 Иногда нужно немного изменить поведение класса — добавить одно условие, поменять одну строчку, подставить другую

content/012-conditions.md

@@ -1,7 +1,7 @@
 # Управляющие конструкции
 
 Хороший код строится из простых и понятных блоков. Мы уже научились избегать лишней вложенности и выходить из метода как
-можно раньше. Но есть ещё одна область, где может скрываться неявная сложность, способная незаметно разрастаться — это *
+можно раньше. Но есть ещё одна область, где может скрываться неявная сложность, способная незаметно разрастаться — это 
 **управляющие конструкции**.
 
 В живом проекте требования неизменно растут. Это нормально: бизнес двигается, пользователи чего-то хотят, а нам

content/014-exceptions.md

@@ -4,6 +4,8 @@
 Ошибки могут возникать по самым разным причинам: от неправильного ввода данных до сбоев в работе внешних сервисов. 
 Поэтому важно правильно обрабатывать ошибки, чтобы ваш код не падал и не оставлял пользователей в недоумении.
 
+<div style="page-break-after: always;"></div>
+
 ### Исключения
 
 Как правило, исключения, которые вы ожидаете и планируете обрабатывать заранее, должны наследоваться от `Exception`.

content/020-copilot.md

@@ -142,7 +142,9 @@ public function generate(): string
 
 private function canTokenExists(string $token): bool
 {
-    return DB::table('tokens')->where('value', $token)->exists();
+    return DB::table('tokens')
+        ->where('value', $token)
+        ->exists();
 }
 ```
 
@@ -184,6 +186,5 @@ LLM не знает, как устроена твоя система. Он пр
 AI — это помощник. Он может ускорить работу.
 Но он не заменит твой выбор, твой стиль, твоё мышление.
 
-Второй пилот не заменит твоё мышление — он просто помогает писать.
-
-А хороший код начинается с тебя, а не с него!
+Второй пилот не заменит твоё мышление — он просто помогает писать. 
+А хороший код начинается с тебя!