WIP

Author: tabuna

content/010-arguments.md

@@ -22,6 +22,10 @@ $fileSystem->write(
 
 ### Необязательные аргументы — в конец
 
+При проектировании методов порядок аргументов имеет значение. 
+Один из самых простых и эффективных способов сделать его чище — располагать необязательные параметры в конце.
+
+Рассмотрим пример:
 ```php
 // Плохо ❌
 $fileSystem->write(
@@ -30,6 +34,9 @@ $fileSystem->write(
     'Пример данных для записи.', // Содержимое
 );
 ```
+Чтобы просто записать файл, нам приходится явно указывать `null` — значение, которое на самом деле нам не нужно.
+
+Куда лучше такой вариант:
 
 ```php
 // Хорошо ✅
@@ -39,20 +46,41 @@ $fileSystem->write(
 );
 ```
 
+А если нужно изменить поведение по умолчанию, мы просто добавим третий параметр:
+
+```php
+// Плохо ❌
+$fileSystem->write(
+    '/path/to/file.txt',         // Путь до файла
+    'Пример данных для записи.', // Содержимое
+    true,                        // Перезаписать файл, если он существует
+);
+```
+
+В этом случае метод будет принимать только обязательные параметры, а необязательные будут в конце. Это делает код чище и понятнее. Так как их можно не указывать, если они не нужны.
+
 ### Как поступить, если аргументов много?
 
-Используйте именованные аргументы
+Иногда метод требует не один-два, а сразу пять или больше параметров. Передавать всё списком в строго заданном порядке — не лучшая идея. Легко перепутать аргументы, особенно если они одного типа. К тому же вызов такого метода выглядит пугающе и плохо читается.
+
+Первое, что приходит на ум это использование ассоциативного массива:
 
 ```php
-// Хорошо ✅
+// Плохо ❌
 $fileSystem->write(
     '/path/to/file.txt',
     'Пример данных для записи.',
-    debug: true,  // Именованный параметр
+    [
+        'encoding' => 'UTF-8',
+        'overwrite' => true,
+        'debug' => true,
+    ]
 );
 ```
 
-Если параметры логически связаны, создайте объект, инкапсулирующий их. Например:
+Это отвратительный способ. Такой подход не даёт информации о том, какие параметры действительно ожидаются, и не позволяет IDE подсказывать возможные опции. Более того, здесь нет проверки типов — любые ошибки проявятся только во время выполнения. Это усложняет отладку и увеличивает вероятность багов.
+
+Другая популярная попытка — создать объект, инкапсулирующий значения. Например:
 
 ```php
 $config = new Config($encoding, $overwrite, $debug);
@@ -65,10 +93,31 @@ $fileSystem->write(
 );
 ```
 
-Такой подход упрощает передачу параметров, делает код самодокументируемым и облегчает переиспользование.
+Это лишь видимость решения. Мы создали объект, который сам по себе бессмысленен: он не содержит поведения и не добавляет никакой бизнес-логики. Фактически, это тот же массив, только завернутый в класс. Польза от него — разве что автодополнение в IDE. Но теперь мы должны создавать или таскать этот объект везде, где вызываем метод `write`, что только усложняет код.
 
-Но есть и намного лучше вариант, использоваение fluent-интерфейс.
-Это это объект, методы которого возвращают самого себя, позволяя вызывать методы цепочкой:
+
+Если язык поддерживает именованные аргументы и их количество очень-очень ограничено, стоит использовать их:
+```php
+$fileSystem->write(
+    '/path/to/file.txt',
+    'Пример данных для записи.',
+    debug: true, // Именованный параметр
+);
+```
+Это уже лучше: вызов становится самодокументируемым, и порядок аргументов не имеет значения.
+
+В случае языков с поддержкой именованных аргументов, можно использовать их:
+
+```php
+$fileSystem->write(
+    '/path/to/file.txt',
+    'Пример данных для записи.',
+    debug: true,  // Именованный параметр
+);
+```
+
+Но есть гораздо более выразительный и управляемый способ — **fluent-интерфейс**. 
+Это объект, методы которого возвращают самого себя, позволяя вызывать их цепочкой:
 
 ```php
 // Хорошо ✅
@@ -80,11 +129,11 @@ $fileSystem
     ->write('Пример данных для записи.');
 ```
 
+В этом подходе сразу видно, что происходит. Каждый шаг отделён, названия методов описывают действия, и вся цепочка читается как связный набор настроек. Такой стиль легко расширяется, хорошо покрывается тестами и открывает дорогу к более гибкой архитектуре.
 
+### Предпочитайте объекты
 
-### Предпочитайте обьекты
-
-Строки, булевые, числа очень удобны в начале разработки, но проект раснет, логика усложняется, и эти простые значения не справляются.
+Строки, булевые, числа очень удобны в начале разработки, но с течением времени, логика усложняется, и эти простые значения не справляются.
 
 Что раньше было флагом `true`, теперь требует дополнительных условий:
 *если админ*, *если включён режим отладки*, *если пользователь подтвердил e-mail*.

content/011-remove.md

@@ -36,10 +36,12 @@
 
 ```php
 // Плохо ❌
-class AuthService
+class Auth
 {
-    public function generateAccessToken(int $userId): string
+    public function generateAccessToken(): string
     {
+        $userId = $this->user->getKey(),
+    
         // Log::info("Generating token for user: $userId");
 
         $payload = [
@@ -82,12 +84,12 @@ class AuthService
 
 ```php
 // Хорошо ✅
-class AuthService
+class Auth
 {
-    public function generateAccessToken(int $userId): string
+    public function generateAccessToken(): string
     {
         return $this->signToken([
-            'sub' => $userId,
+            'sub' => $this->user->getKey(),
             'exp' => $this->calculateExpiration(),
         ]);
     }

content/014-tests.md

@@ -1,8 +1,6 @@
 # Тесты
 
-Мне не нравится, как испортили слово **тестирование**.
-
-Тестирование испортили. Изуродовали. Потому что часто под этим подразумевают ручную проверку, что продукт работает как задумано после изменений. Это не то, что нужно разработчику, нам нужен контроль качества.
+Слово **тестирование** испортили и изуродовали. Потому что часто под этим подразумевают ручную проверку, что задача которую делал разработчик работает как задумано после изменений. Это не то что нужно разработчику, нам нужен контроль качества.
 
 Многие до сих пор думают, что тестированием занимается кто-то другой: тестировщик, QA-инженер, автоматизатор или великий господин начальник. Это не так.
 
@@ -11,7 +9,7 @@
 
 ### Больше юнит-тестов, меньше всего остального
 
-В мире тестирования есть много терминов: интеграционные, e2e, smoke, UI, acceptance, snapshot, regression… Становится страшно даже начинать.
+В мире тестирования есть много терминов: интеграционные, e2e, smoke, UI, acceptance, snapshot, regression… Становится страшно даже начинать перечислять. Но непосредственно на качество кода влияет только один вид тестов — юнит-тесты.
 
 Почему? Потому что они:
 - Проверяют маленькие части кода (функции, методы, классы).
@@ -47,7 +45,9 @@ public function test_returns_moon_phase_data(): void
 
 ```
 
-Но как именно работает функция, вычисляющая фазу Луны? Как она получает данные о Луне? Как она обрабатывает дату? И вроде бы всё хорошо, но это обманка. Такой тест ничего не говорит о логике внутри. Он — витрина. Он проверяет фасад, но не фундамент. Он проверяет только конечный результат. 
+Это хороший тест, который проверяет, что API возвращает правильные данные для известной даты. Он проверяет, что ответ содержит нужные поля и что значения в них соответствуют ожидаемым.
+
+Но как именно работает функция, вычисляющая фазу Луны? Как она получает данные о Луне? Как она обрабатывает дату? И вроде бы всё хорошо, но это обманка. Такой тест ничего не говорит о логике внутри. Он — витрина. Он проверяет фасад, но не фундамент. Он проверяет только конечный результат, это должно быть как вишенка на торте, а не основа.
 
 Мы можем написать в код прямо контроллере и добавить туда с десяток функций, которые будут вызывать другие функции, и в итоге получим правильный ответ. Но это фигня.