WIP

Author: tabuna

content/001-preface.md

@@ -30,7 +30,7 @@
 ### Для кого предназначена эта книга
 
 Предполагается, что читателем книги в первую очередь станет специалист начального уровня, уже принимавший участие хотя
-бы в одном коммерческом, личном или учебном проекте. Но и опытные специалисты найдут здесь полезные идеи — особенно если их профессиональный путь был связан с одной командой, 
+бы в одном коммерческом, личном или учебном проекте. Но и опытные специалисты найдут здесь полезные идеи — особенно если их профессиональный путь был связан с одной командой,
 похожими задачами и устойчивыми привычками. Она поможет лучше понять, как работать в команде и избегать раздражения у коллег.
 Для руководителей она будет полезна как пособие для команды и как источник рекомендаций при ревью кода.
 

content/014-exceptions.md

@@ -1,7 +1,7 @@
 # Обработка ошибок
 
-Каждый раз, когда вы пишете код, вы должны помнить о том, что он может сломаться. 
-Ошибки могут возникать по самым разным причинам: от неправильного ввода данных до сбоев в работе внешних сервисов. 
+Каждый раз, когда вы пишете код, вы должны помнить о том, что он может сломаться.
+Ошибки могут возникать по самым разным причинам: от неправильного ввода данных до сбоев в работе внешних сервисов.
 Поэтому важно правильно обрабатывать ошибки, чтобы ваш код не падал и не оставлял пользователей в недоумении.
 
 <div style="page-break-after: always;"></div>
@@ -39,7 +39,7 @@ try {
 }
 ```
 
-Пример – «смертельно» опасен: проблема произошла, но никто об этом не узнает. 
+Пример — «смертельно» опасен: проблема произошла, но никто об этом не узнает.
 Главное — не потерять факт ошибки. Так делать нельзя: ошибка уходит в тень, вы теряете информацию.
 
 
@@ -62,14 +62,14 @@ try {
 } catch (ExternalApiException $exception) {
     Log::warning('Не удалось получить приветствие', [
         'arguments' => ['time' => $time],
-        'exception' => $exception
+        'exception' => $exception,
     ]);
 
     $message = 'Добро пожаловать!';
 }
 ```
 
-### Ясные ошибки 
+### Ясные ошибки
 
 Сообщения об ошибках должны быть максимально информативными и конкретными.
 Вместо абстрактного «RuntimeException» нужно описывать, что именно произошло и где:
@@ -78,15 +78,15 @@ try {
 ```php
 // Плохо [✗]
 foreach ($users => $user) {
-   if($user->isActive()){
+   if ($user->isActive()) {
        throw new Exception(
             'Пользователь должен быть неактивен для удаления'
         );
    }
 }
 ```
 
-Невозможно понять, какой именно пользователь вызвал ошибку. 
+Невозможно понять, какой именно пользователь вызвал ошибку.
 Чтобы исправить, нужно добавить контекст:
 
 ```php
@@ -118,15 +118,15 @@ try {
 
 <div style="page-break-after: always;"></div>
 
-В другой месте:
+В другом месте:
 
 ```php
 try {
     // ...
 } catch (Throwable $e) {
     file_put_contents('log-user.txt', json_encode([
         'line' => $e->getLine(),
-        'status' => 500
+        'status' => 500,
     ]));
 }
 ```
@@ -157,25 +157,25 @@ function logException(Throwable $e): void
 
 Важно также не писать всё бесконтрольно в один файл, так как его содержание будет расти.
 Это может вылиться в то, что любимая IDE или редактор не смогут открыть файл на 30 ГБ,
-не говоря уже о том, чтобы осуществить эффективный поиск по нему. 
+не говоря уже о том, чтобы осуществить эффективный поиск по нему.
 Чтобы такого не произошло, можно настроить ротацию логов — например, чтобы каждый новый день старый лог переименовывался и архивировался, а спустя некоторое время удалялся.
 Так у вас будет меньше мусорных данных, которые не нужны в контексте.
 
-Но просто собирать логи мало. Нужно, чтобы вы сразу узнавали о проблемах. 
-Для этого подключают централизованные системы мониторинга: Sentry, Graylog, ELK или другие. 
+Но просто собирать логи мало. Нужно, чтобы вы сразу узнавали о проблемах.
+Для этого подключают централизованные системы мониторинга: Sentry, Graylog, ELK или другие.
 Они собирают все ошибки в одном месте, позволяют группировать и отслеживать повторяющиеся баги, а при необходимости — шлют оповещения на почту или в мессенджеры.
 
 ### Отладка
 
-Среди разработчиков распространено мнение, что пошаговая отладка, например, с помощью Xdebug, — признак хорошего специалиста. 
+Среди разработчиков распространено мнение, что пошаговая отладка, например, с помощью Xdebug, — признак хорошего специалиста.
 Выглядит это следующим образом: разработчик ставит точку остановки, затем начинает "шагать" по коду, наблюдает за значениями переменных, отслеживает условные переходы — словно читает чужие мысли.
 Якобы именно так приходит понимание, «как всё устроено».
 
 Но позвольте — если вам нужно так делать, значит, что-то пошло не так!
 
 Это не норма. Значит, ваш код неочевиден, сложен и плохо структурирован.
 
-Настоящая причина, по которой вам нужно пошагово проходить каждую строчку, в том, что вы не понимаете, что происходит в системе. 
+Настоящая причина, по которой вам нужно пошагово проходить каждую строчку, в том, что вы не понимаете, что происходит в системе.
 И не потому что вы недостаточно умны, а потому что код запутан. В нём всё связано со всем, всё влияет на всё, и даже чтобы просто проверить, вам приходится запускать сервер, кликать через интерфейс и ставить точку остановки где-то внутри `shouldGoOutside()`.
 
 Представим, что система должна вернуть рекомендацию пользователю — выходить ли на улицу:
@@ -209,7 +209,7 @@ function shouldGoOutside(array $weather): bool
 ```
 
 Здесь есть и вложенные блоки `try-catch`, и `if` внутри `if`, и цикл с ловлей исключений «внутри» функции.
-Без отладки трудно понять, за какой именно шаг «цепи» падает — внешняя обработка или внутренняя. 
+Без отладки трудно понять, за какой именно шаг «цепи» падает — внешняя обработка или внутренняя.
 
 <div style="page-break-after: always;"></div>
 
@@ -228,7 +228,7 @@ final class DecisionEngine
     public function shouldGoOutside(array $weather): bool
     {
         foreach ($this->rules as $rule) {
-            if (!$rule->passes($weather)) {
+            if (! $rule->passes($weather)) {
                 return false;
             }
         }

content/016-remove.md

@@ -1,8 +1,8 @@
 # Не бойся удалять код
 
-Удаление кода так же важно, как и его написание. Это акт заботы о проекте. 
+Удаление кода так же важно, как и его написание. Это акт заботы о проекте.
 Вы следите за его чистотой, избавляетесь от ненужного, делаете структуру понятнее и помогаете другим быстрее разобраться, как всё устроено.
-Это ни в коем случае не поражение, это не «зря писал». 
+Это ни в коем случае не поражение, это не «зря писал».
 Это развитие. Это значит, что вы переросли старое решение, нашли лучшее или поняли, что оно больше не нужно.
 
 
@@ -15,14 +15,14 @@
 И вот тут появляется важный момент: последовательность.
 Когда код меняется, названия устаревают. Логика перерастает своё оформление — нужно адаптироваться как можно быстрее и без страха.
 
-Когда-то метод `validate()` проверял логин и пароль. 
-Сегодня он уже проверяет два токена, куки и капчу. 
-А называется всё ещё `validate()`. И это вводит в заблуждение. 
+Когда-то метод `validate()` проверял логин и пароль.
+Сегодня он уже проверяет два токена, куки и капчу.
+А называется всё ещё `validate()`. И это вводит в заблуждение.
 Сегодняшнему разработчику нужно читать реализацию, потому что по названию уже ничего не понятно.
 
 
 Код меняется, и ему нужно давать возможность изменяться — в том числе через переименование и удаление.
-Не стоит оставлять старое имя «ради совместимости» или из лени. Это путь к путанице. 
+Не стоит оставлять старое имя «ради совместимости» или из лени. Это путь к путанице.
 Пусть код выглядит так, как он работает сейчас, а не когда-то давно.
 
 
@@ -65,8 +65,8 @@ public function generateAccessToken(): string
 ```
 
 Во-первых, шум. Когда открываешь файл и видишь кучу закомментированного кода, начинаешь гадать: это ещё работает?
- Это было важно? А может, наоборот, это старая логика, которую уже заменили?
- Такой шум мешает сосредоточиться и понять, какой код сейчас «правильный».
+Это было важно? А может, наоборот, это старая логика, которую уже заменили?
+Такой шум мешает сосредоточиться и понять, какой код сейчас «правильный».
 
 Во-вторых, портится дисциплина.
 Стоит один раз оставить закомментированный фрагмент — и понеслось. Один, второй...

content/020-copilot.md

@@ -59,9 +59,9 @@ LLM не откажет. Он скажет: «Да, командир!» — и 
 приведёт к серьёзным проблемам.
 
 
-"Второй пилот" — помощник другого типа. 
+"Второй пилот" — помощник другого типа.
 
-Он не будет указывать на архитектурные проблемы или спорные решения, пока его об этом не попросите. 
+Он не будет указывать на архитектурные проблемы или спорные решения, пока его об этом не попросите.
 Его задача — помогать вам как можно быстрее двигаться к результату, решать бизнес-проблемы здесь и сейчас.
 Но и большинство разработчиков настроены точно так же: задача должна быть закрыта, сроки — вчера, и мало кто будет
 тратить время, чтобы просить помощника подумать над более выразительными именами переменных, архитектурой или стилем.
@@ -80,7 +80,7 @@ LLM не откажет. Он скажет: «Да, командир!» — и 
 
 Появляется асимметрия. Поверхность кажется правильной, но под капотом — несовместимость.
 
-Мы уже несколько раз в книге говорили о симметрии, но давайте повторим. 
+Мы уже несколько раз в книге говорили о симметрии, но давайте повторим.
 И посмотрим на небольшой пример импортера исторических данных о погоде:
 
 ```php
@@ -92,7 +92,7 @@ $importer->import([
 ]);
 ```
 
-Его мог бы написать любой и выглядит вполне разумно. Но этот класс — часть процесса импорта/экспорта. 
+Его мог бы написать любой, и выглядит вполне разумно. Но этот класс — часть процесса импорта/экспорта.
 LLM может не знать о том, что класс экспорта выдаёт не набор XML-структур, а zip-архив:
 
 ```php
@@ -115,8 +115,8 @@ LLM не «ошибся». Он просто не увидел целиком в
 Именно контекст определяет смысл.
 И если ты его теряешь — модель его точно не найдёт.
 
-Другой пример такой асимметрии — если мы попросим LLM, например, внести проверку на 
-уникальность в базе данных: 
+Другой пример такой асимметрии — если мы попросим LLM, например, внести проверку на
+уникальность в базе данных:
 
 ```php
 class TokenService
@@ -178,15 +178,15 @@ LLM не знает, как устроена твоя система. Он пр
 Сгенерированный код может выглядеть и работать правильно, но разработчик становится не уверен в его деталях, не понимает всех нюансов и не чувствует связи с ним.
 Он становится чем-то внешним — как инструмент, который решил задачу, но не передал опыт.
 
-В результате со временем может очень сильно снизиться мотивация и вовлечённость разработчика. 
+В результате со временем может очень сильно снизиться мотивация и вовлечённость разработчика.
 Чтобы такого не допускать, нужно не просто «принимать» результат от LLM, а делать его "своим".
 
-* Понимать, откуда он взялся.
-* Переписывать под собственный стиль.
-* Встраивать в архитектуру осознанно.
+- Понимать, откуда он взялся.
+- Переписывать под собственный стиль.
+- Встраивать в архитектуру осознанно.
 
 AI — это помощник. Он может ускорить работу.
 Но он не заменит твой выбор, твой стиль, твоё мышление.
 
-Второй пилот не заменит твоё мышление — он просто помогает писать. 
+Второй пилот не заменит твоё мышление — он просто помогает писать.
 А хороший код начинается с тебя!