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

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

Метод должен быть запросом или командой. Не оба.

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

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

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

Методы запроса должны называться существительным или прилагательным, а команды — активными глаголами.

// bad: named as a command but has no side-effects 
$order->calculateTotal();  
// better: named as a query 
$order->total();  
// bad: you'd think it returns a cancellation object
$order->orderCancellation();  
// better: it changes the order state, so it’s a command that should be named with an active verb. 
$order->cancel();

Избегайте использования «не»

Использование «не» в именах методов может показаться немного более выразительным, но почти всегда это плохая идея.

Если у вас есть метод $invoice->notPaid(), у вас должен быть и противоположный метод $invoice->paid(). Вы просто не можете использовать двойное отрицание !$invoice->notPaid() — мой мозг болит, пытаясь понять это.

Добавление второго метода paid() прояснит ситуацию, но ваше приложение будет использовать все возможные комбинации, в том числе и «не оплачен счет». Некоторые люди выберут правильный метод, но большинство сделает то, что обычно делают программисты: добавят оператор not и покончат с этим.

Избавьте себя от боли и избегайте использования «не» в именах методов. У нас уже есть оператор для этого.

Назовите методы после понятия, которое они представляют

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

// bad: I might have to change the implementation and travel by car 
public function travelByPlane()
{   
    // code to travel by plane 
}  
// better: it allows me to change the implementation without changing the method’s name 
public function travel() 
{   
    // travel by plane, train, car, bike, food, crawl, anything. 
}

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

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

Избегайте раздутых имен

Хорошие имена методов обычно короткие. Если их нет, то тому две причины:

  1. Сам метод делает слишком много вещей, и нам нужно более длинное, раздутое имя, чтобы объяснить себя. В идеале метод должен делать одну и только одну вещь. При этом еще большей ошибкой является метод, выполняющий слишком много действий под коротким именем. Лучше быть явным и иметь длинное имя, чем замести все под ковер.
  2. Имя включает ненужную информацию, которая уже может быть получена из существующего контекста.
// poor 
$order->orderRefund();  
// better: 
$order->refund();   

// poor 
$invoice->dueDateHasPassed();  
// better 
$invoice->overdue();

Имена должны быть точными

Иногда у нас есть методы, подразумевающие, что они делают одно, но делают что-то другое. Рассмотрим следующий пример:

class Invoice  
{     
    public function pay()      
    {         
        $this->update(['paid_at' => Carbon::now()]);     
    } 
}

Способ выше врет. Когда кто-то звонит $invoice->pay(), деньги не поступают на мой счет. Что он делает, так это устанавливает атрибут paid_at на текущую дату. Лучший способ выразить это — сказать: «Он помечает счет как оплаченный».

class Invoice
{
    public function markAsPaid()      
    {         
        $this->update(['paid_at' => Carbon::now()]);     
    } 
}

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

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