Гвард (guard)— это фрагмент кода в верхней части функции или метода, который делает return, если выполняется некоторое предварительное условие. Я считаю, что правильное их использование может уменьшить как сложность, так и когнитивную нагрузку кода.

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

1. Код с традиционным If/Else

function calculateSalePrice(Item $item, $discount = 0) : int
{ $price = 0; if ($discount == 0) { $price = $item->getPrice(); } else { $price = calculateDiscountedPrice($item->getPrice(), $discount); } return $price;
}

Функция calculateSalePrice вернет цену продажи товара. В этом методе реализация следует правилу «только один return». Первая строка предлагает дефолтное значение, и будет просто ужасно, если функция его вернет. У нас есть некоторая вложенность, которая займет у нас некоторое время, чтобы мысленно разобраться в ней и полностью понять.

Если считать непустые строки, то этот код занимает около 50% шаблона (boilerplate) и синтаксиса. Это означает, что мы тратим много времени на ввод и чтение бесполезного кода. PHP и JavaScript имеют системы управления памятью, которые не требуют единого выхода, так что давайте рассмотрим альтернативные способы написания этого метода.

2. Код с If/Else и досрочным Return

function calculateSalePrice($item, $discount = 0) { if ($discount == 0) { return $item->getPrice(); } else { return calculateDiscountedPrice($item->getPrice, $discount); }
}

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

Мы уменьшили некоторую когнитивную нагрузку, удалив дефолтный $price = 0;. Поскольку возвращать нулевую цену было бы неправильно, разработчик должен потратить немного времени и убедиться, что она таковой не будет. Если несколько разработчиков смотрели на это много раз в течение жизни проекта, затрачиваемое ими время складывается.

3. Код без Else

function calculateSalePrice($item, $discount = 0) { if ($discount == 0) { return $item->getPrice(); } return calculateDiscountedPrice($item->getPrice, $discount);
}

Логика идентична первым двум примерам. Однако теперь есть явный оператор возврата, и мы сократили функцию еще на две строки кода.

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

4. Код без Else с инвертированным контролем

function calculateSalePrice($item, $discount = 0) { if ($discount > 0) { return calculateDiscountedPrice($item->getPrice, $discount); } return $item->getPrice();
}

Логика этого противоположна примеру 3. Теперь мы используем правильный гвард. Мы переместили главную цель функции в основную часть без вложенности и обработали менее распространенный случай гвардом.

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

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

На этом этапе рефакторинга вы можете заметить, что этот код всегда был тернарным. Вы можете прийти к выводу, что нужно просто переписать это как тернар и пойти дальше. Однако, если на время обслуживания вам придется будет добавить второй гвард, то вы будете иметь diff в 100% для метода, когда вы ввели это изменение. Мы бы сохранили несколько байтов кода сейчас для более сложной проверки позже.

Примеры более практичного кода

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

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

class Post
{ public function canEdit(User $user) : bool { $canEdit = false; if (($user->getRole() == 3 && $this->getEditorId() == $user->getId()) || $user->getRole() > 5 || ($this->getAuthorId() == $user->getId() && $this->created_at < time() — 2592000)) { $canEdit = true; } return $canEdit; }
}

Сообщение является редактируемым, если:

  • Пользователь является редактором этого поста или администратором
  • Пользователь является автором, и сообщение было написано в последние тридцать дней.

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

Представьте, что вам дается новое требование: «Роль 4 может редактировать сообщения на боковой панели (sidebar)». Единственный if имеет силу притяжения; он нас затягивает. Скорей всего, увидев бардак, мы сдадимся и вставим еще || ($user->getRole() == 4 && $this->getCreatedOn < time() — 518400), || ($user->getRole() == 4 && $this->getCreatedOn < time() — 518400), а затем перейдем к следующему проекту. Подобные сложный условия имеет тенденцию расти со временем.

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

Исходный отрефакторенный код

class Post
{ public function canEdit(User $user) : bool { $isEditor = $user->getRole() == 3 && $this->getEditorId() == $user->getId(); $isAdmin = $user->getRole() > 5; $isAuthor = $this->getAuthorId() == $user->getId(); $isTooOld = $this->created_at < time()—2592000; if ($isEditor || $isAdmin) { return true; } if ($isAuthor && !$isTooOld) { return true; } return false; }
}

Сканируем этот код снизу вверх и сразу видим, что по умолчанию возвращается значение false. Мы можем подумать: «Хорошо, мы в безопасности. Сообщения, как правило, не редактируются». Теперь мы можем свободно просмотреть весь метод, чтобы увидеть условия, при которых сообщение можно редактировать.

Вероятно вы заметили, что строки 12 и 16 могут быть объединены в один оператор OR. Если бы мы решили сделать это, то увеличили бы сложность и уменьшили читабельность. Не думаю, что сохранили бы что-нибудь, кроме количества строк.

Давайте вернемся к новому требованию «Роль 4 может редактировать сообщения на боковой панели (sidebar)». С отрефакторенный кодом это должно быть намного проще. Мы добавим гвард для нового условия и посмотрим на разницу.

Начальный рефакторинг с новым условием

class Post
{ public function canEdit(User $user) : bool { $isEditor = $user->getRole() == 3 && $this->getEditorId() == $user->getId(); $isAdmin = $user->getRole() > 5; $isAuthor = $this->getAuthorId() == $user->getId(); $isSupervisor = $this->getRole() == 4; $isSidebarPost = $this->getType() == 8; $isTooOld = $this->created_at < time()—2592000; if ($isSupervisor && $isSidebarPost) { return true; } if ($isEditor || $isAdmin) { return true; } if ($isAuthor && !$isTooOld) { return true; } return false; }
}
// Git Diff
@@ -7,8 +7,14 @@ class Post $isAuthor = $this->getAuthorId() == $user->getId();
+ $isSupervisor = $this->getRole() == 4;
+ $isSidebarPost = $this->getType() == 8; $isTooOld = $this->created_at < time()—2592000;
+ if ($isSupervisor && $isSidebarPost) {
+ return true;
+ }
+ if ($isEditor || $isAdmin) {

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

Рефакторинг роста путем удаления магических чисел

Представьте, что нам нужно изменить тип, который идентифицирует сообщения на боковой панели. Сообщения боковой панели в настоящее время идентифицируются как 8. Вероятно, это число используется по всему коду в разных местах. Если нам нужно изменить это значение на 11, то наш единственный вариант — сделать поиск по всему коду и уповать на то, что найдем все места его использования. И мы можем только надеяться, что это где-то это не задано как $type = $primaryType + 1;

Мы могли бы избавиться от подобного, просто создав константу в классе Post для представления типа боковой панели. Можно добавить новую const SIDEBAR_TYPE = 8; а затем использовать её в нашем коде. Затем мы можем преобразовать наши сравнения так: $isSidebarPost = $this->getType() == self::SIDEBAR_TYPE;

Удаление магических чисел — всегда положительное изменение. Если новые требования диктуют изменить тип боковой панели, мы можем сделать это в одном месте. Diff снова будет очень маленьким. Удалив магические числа, мы добавили перспективу и самодокументирование. Тем не менее, мы все еще можем сделать еще лучше.

Давайте представим еще один сценарий роста, в котором мы собираемся добавить второй тип боковой панели. Теперь нам нужно, чтобы 8 и 11 были сообщениями на боковой панели. Простая идея с константой рушится. Наша задача — найти все места в коде, где используется self::SIDEBAR_TYPE и обновить их, добавив сравнения с двумя разными константами. Вместо того, чтобы менять эту логику по всему коду, мы проведем рефакторинг и упростим.

Добавим новый метод, который будем использовать вместо этих сравнений. Он будет выглядеть как $isSidebarPost = $this->isSidebarPost(); Новый метод объединяет обе проверки в одну и дает место для будущего рефакторинга. Мы включим это в наш последний пример.

Полный пример

class Post
{ protected $sidebarTypes = [8, 11]; protected $authorEditTimeout = 2592000; ... public function canEdit(User $user) : bool { if ($user->isAdmin()) { return true; } if ($user->isSupervisor() && $this->isSidebarPost()) { return true; } if ($user->isEditor() && $this->isEditedBy($user)) { return true; } if ($this->isAuthoredBy($user) && !$this->isTooOldToEdit()) { return true; } return false; } ... public function isAuthoredBy(User $author) : bool { return $this->author->getId() === $author->getId(); } public function isEditedBy(User $editor) : bool { return $this->editor->getId() === $editor->getId(); } public function isSidebarPost() : bool { return in_array($this->type, self::$sidebarTypes); } public function isTooOldToEdit() : bool { return $this->created_at < (time()—self::$authorEditTimeout); }
}
class User
{ const ROLE_EDITOR = 3; const ROLE_SUPERVISOR = 4; const ROLE_ADMIN = 5; public function isEditor() : bool { return $this->role == self::ROLE_EDITOR; } public function isSupervisor() : bool { return $this->role == self::ROLE_SUPERVISOR; } public function isAdmin() : bool { return $this->role == self::ROLE_SUPERVISOR; }
}

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

Резюме

В PHP и JavaScript гварды могут значительно сократить шаблонный код (boilerplate) в методе и значительно упростить код. Кроме того, они представляют собой паттерн, который будет более удобен в обслуживании в течение всего жизненного цикла проекта и приведет к уменьшению diff’ов и упрощению кода. В стремлении снизить стоимость обслуживания кода нужно помнить:

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

Вперед к великим делам!

Автор: Craig Davis
Перевод: Demiurge Ash

Источник: laravel.demiart.ru