4 правила хорошего кода

Давай осмысленные имена переменным, функциям и классам.

Не стоит стесняться длинных названий переменных и функций. Я всегда предпочитаю что-то вроде такого:

<?php
...
$filterParamFromRequest = $request->input('productLength');

function getFilteredParamString($data) {
	...
}

вместо

<?php
...
$fpr = $request->input('param');

function fpString($data) {
	...
}

Что же касается классов, то я предпочитаю закладывать в название класса как можно больше информации. Если мы работаем без пространств имен, то в моем коде это может быть что-то подобное:

<?php

class TournamentCalculatorService {
	...
}

Если мы имеем дело с проектом, где поддерживаются пространства имен, то при помощи каталогов и неймспейсов мы можем сделать путь к классу максимально информативным. Например, таким:

<?php

use App\Services\Game\Tournament\CalculatorService;

Сам же код класса может выглядеть так:

<?php

namespace App\Services\Game\Tournament;

class CalculatorService {
	...
}

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

Снабжай код подробными комментариями

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

Пример сложного участка кода, который я снабжаю комментариями:

<?php
...
public function saveAndAddTeamToTournament(Tournament $tournament, User $createdByUser, Team $newTeam){
    //Команда уже существует. Метод предполагает что будет передана не сохраненная ранее команда
    if($newTeam->exists){
        throw new \Exception(__('messages.team_already_exists'));
    }

    //Нет подключенного игрового аккаунта
    if(!$this->userHasGameLinkedAccount($createdByUser, $tournament->game)){
        ...
    }

    //Турнир не командный
    if(!$tournament->isTeam()){
        ...
    }

    //Смотрим, попадаем ли мы на период приема заявок этого турнира
    if(!$tournament->isRequestAvailable()){
        ...
    }

    //Пользователь уже участвует в этом турнире
    $member = UserTournamentMember::where('user_id', $createdByUser->id)
        ->where('tournament_id', $tournament->id);
    if($member->exists()){
        ...
    }

    ...
    
    return $teamTournamentMember;
}

Когда ты пишешь код здесь и сейчас, ты, безусловно, понимаешь, что ты пишешь и зачем. Но не стоит думать, что твой мозг может помнить все, что он сгенерировал ранее. Детали, безусловно, забываются со временем. Так устроена наша память. Если ты не оставишь хороших комментариев в своем же коде, причем несмотря на то, что у тебя информативные названия функций и переменных, через неделю или месяц, тебе придется снова вникать в то, что ты написал. Хорошие же комментарии, как ты уже догадался, позволят тебе сделать это максимально быстро.

Делай README

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

Декомпозируй логику на составляющие

Есть такой принцип единственной ответственности (Single Responsibility), который применяется в объектно-ориентированном проектировании (хотя, я уверен, что он применяется не только в ООП). Если вкратце, то он означает, что нельзя валить всю логику в одну функцию/класс. Другими словами, старайтесь делить большую и сложную логику на отдельные составляющие (пространства имен, классы и функции), отвечающие за свой узкий круг задач. Так вам будет гораздо проще следить за работоспособностью проекта, а при работе в командах вы сможете гибко распределять задачи по разным исполнителям.

Выноси настройки в отдельные файлы конфигурации или файлы окружения

Это правило я для себя выработал, глядя на то, как устроены большие системы, вроде CMS, где есть отдельный раздел "Настройки" и в нем можно найти огромное количество самых разных настроек, отвечающих за абсолютно не связанные между собой функции. Другими словами, если вы разрабатываете веб-приложение или сайт и вдруг сталкиваетесь с моментом, когда в коде вставляете конкретное число (например количество элементов на странице), конкретный идентификатор (например идентификатор пользователя-администратора) или строку (например, имя приложения), то в большинстве случаев это сигнал о том, что это значение нужно вынести в конфигурационный файл, а на его месте поставить обращение к конфигурации.

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

Заключение

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

Бери на вооружение и применяй!