Заметки о codestyle

Довольно часто сталкиваюсь с вопросом касательно качества кода: "Почему написано именно так, а не так?". И я объясняю каждый раз. Именно поэтому решил составить эдакую заметку с некоторыми примерами и объяснениями.

Второй возникающий вопрос: "Где научился так красиво писать?". Ответ на который будет к концу статьи.

Приведу три примера, с которыми сталкиваюсь чаще всего.

Пример 1

use App\Models\Payment;
use Illuminate\Database\Eloquent\Model;

class Foo extends Model {
  public function user(){
    return $this->hasOne('App\Models\User');
  }

  public function payments(){
    return $this->hasMany(Payment::class);
  }
}

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

Начнём с того, что открывающиеся фигурные скобки лучше переносить на новую строку. Это позволит сделать код более приятным в чтении (Привет, PSR-12).

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

Также отступы следует делать в 4 пробела, так как такой код лучше воспринимается человеческим глазом. Символы табуляции лучше не использовать, т.к. на каждом устройстве в каждом окружении может по-разному быть настроен размер табуляции, и если у одного код будет выглядеть так:

class Foo
{
    public function user()
    {
        //
    }
}

То у другого он может быть таким:

class Foo
{
        public function user()
        {
                //
        }
}

Или таким:

class Foo
{
  public function user()
  {
    //
  }
}

Согласитесь, разница ощутима. А символ "пробела" он и в Африке символ "пробела", отображающийся на всех устройствах одинаково.

Размер в два символа лучше не использовать по той причине, что код становится нечитабельным и выглядит как "по-линейке" - в одну слегка кривую вертикальную линию. И отследить в таком массиве вложенные операторы становится проблемной задачей.

Итак, после ревью код будет выглядеть так:

use App\Models\Payment;
use App\Models\User;
use Illuminate\Database\Eloquent\Model;

class Foo extends Model
{
    public function user()
    {
        return $this->hasOne(User::class);
    }

    public function payments()
    {
        return $this->hasMany(Payment::class);
    }
}

Пример 2

Недавно встретил такой участок кода (вставлю картинкой, чтобы не нарушить его вид):

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

Данный участок очень плохо читается. Приходится вычитывать каждое слово с целью понять что в нём происходит и не пропустил ли чего при чтении.

Проведём код-ревью:

class NewsService
{
    public function sendNews(EmployerNews $employerNews)
    {
        $this->dispatch($employerNews, WorkPositionIdsJob::class);
        $this->dispatch($employerNews, WorkPositionTypesJob::class);
        $this->dispatch($employerNews, EmployerIdsJob::class);
    }

    protected function dispatch(EmployerNews $news, string $class): void
    {
        $job   = $this->job($news, $class);
        $delay = $this->delay();

        dispatch($job)->delay($delay);
    }

    protected function job(EmployerNews $news, string $job): AbstractJob
    {
        return new $job($news->getAttributes());
    }

    protected function delay(): Carbon
    {
        return Carbon::now()->addSecond();
    }
}

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

И не спрашивайте зачем ставить в очередь на 1 секунду позже - мы обращаем внимание на код-стайл, а не на логику.

То же самое касается и примерно таких проблемных участков, как:

switch($value){
    case 'foo':
        //
        break;
    case 'bar':
        //
        break;
}

if ($employerPriceCategory->default) {
    return false;
}
$defaultCategory = EmployerPriceCategory::where('default', true)
    ->first(['id']);
Employer::query()
    ->where('employer_price_category_id', $employerPriceCategory->id)
    ->update([
        'employer_price_category_id' => $defaultCategory->id,
    ]);

$districts = $this->getDistricts();
$this->output->writeln('districts: ' . sizeof($districts));
$period = $this->getPeriod();
foreach ($period as $start) {
    $end = $start->copy()->endOfDay();
    $this->output->writeln('date = ' . $start->format('Y-m-d'));
    //
}

Это же просто ужас! Как такое вообще можно читать? А писать?!

Давайте отрефакторим их!

switch($value)
{
    case 'foo':
        //
        break;

    case 'bar':
        //
        break;
}

if ($employerPriceCategory->default) {
    return false;
}

$defaultCategory = EmployerPriceCategory::query()
    ->select(['id'])
    ->where('default', true)
    ->first();

Employer::query()
    ->where('employer_price_category_id', $employerPriceCategory->id)
    ->update(['employer_price_category_id' => $defaultCategory->id]);

Мы давно пережили времена недостатка места на дисках и не стоит дорожить лишним символом "пробела", который компилятор всё-равно удалит для себя. Это обычная экономия на спичках. Зачем усложнять жизнь не только себе, но и тем, кто после Вас будет поддерживать этот код? Заканчивайте какать там, где едите.

Пример 3

Помимо вставки дополнительных символов "пробела" и переносов строк, старайтесь разделять код на логические блоки.

Логический блок - это участок кода состоящий из нескольких строк, объединённых между собой какой-либо общей чертой.

Для примера возьмём следующий участок:

$salaryFirstBaseEmployer = $employer->salaryBases->first()->salary_base;
$salaryLastBaseEmployer = $employer->salaryBases->last()->salary_base;
$begin = Carbon::parse('2020-05-01')->startOfMonth()->startOfDay();
$end = $begin->clone()->endOfMonth()->endOfDay();
$endMonth = $begin->clone()->endOfMonth();
$startPeriod = new CarbonPeriod($begin, $end);
$endPeriod = new CarbonPeriod($begin, $end);

В нём мы видим непонятный массив текста. Отформатируем его, разбив на логические блоки:

$salaryFirstBaseEmployer = $employer->salaryBases->first()->salary_base;
$salaryLastBaseEmployer  = $employer->salaryBases->last()->salary_base;

$begin = Carbon::parse('2020-05-01')->startOfMonth()->startOfDay();

$end      = $begin->clone()->endOfMonth()->endOfDay();
$endMonth = $begin->clone()->endOfMonth();

$startPeriod = new CarbonPeriod($begin, $end);
$endPeriod   = new CarbonPeriod($begin, $end);

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

Заключение

Очень давно мне дали дельный совет:

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

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