PHP Code Style Conventions
В данной статье рассматривается подход к написанию и оформлению PHP кода. Нижеизложенные моменты были сформированы путем анализа существующих подходов компаний и личного опыта.
Правила именования файлов и папок
Все названия для папок и файлов должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).
Папки
Все папки именуются в нижнем регистре с разделением слов с использованием символа — (минус).
Если папка хранит в себе классы, которые относятся к пространству имен (namespace), то папка именуется в соответствии с названием пространства имен (namespace).
Разрешенные символы для именования папок: латинские буквы и символ — (минус).
Файлы
Все файлы, относящиеся к проекту, именуются в нижнем регистре с разделением слов с использованием символа — (минус).
Если файл является файлом класса, то именуется в соответствии с названием класса.
Правила именования пространств имен, классов, методов и переменных
Все названия должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).
Пространства имен
Названия пространств имен должны быть в нижнем регистре и состоять из одного слова. В случае необходимости именовать пространств имен более одного слова производится дробление на составные части, являющиеся вложенными пространствами имен.
Классы
Названия классов должны соответствовать PascalCase . В PascalCase каждое слово начинается с заглавной буквы.
Трейты имеют постфикс Trait . Интерфейсы имеют постфикс Interface . Абстрактные классы имеют префикс Abstract .
Методы
Названия методов должны соответствовать camelCase . camelCase должен начинаться со строчной буквы, а первая буква каждого последующего слова должна быть заглавной. Все слова при этом пишутся слитно между собой
К названиям методов применяются следующие правила:
- Название метода должно передавать намерения программиста
- Название метода должно сообщить, почему этот метод существует, что он
делает и как используется ( isPostRequest , getRequestType , parseSchemaElement , renderPageWithSetupsAndTeardowns ) - Название метода не должно быть коротким
- Название метода должно начинаться с глагола
- Названия boolean методов должны содержать глагол is , has или can
Переменные
Названия переменных должны соответствовать camelCase . camelCase должен начинаться со строчной буквы, а первая буква каждого последующего слова должна быть заглавной. Все слова при этом пишутся слитно между собой
Константы должны быть соответствовать UPPER_CASE_SNAKE_CASE . В UPPER_CASE_SNAKE_CASE все слова пишутся заглавными буквами, а пробелы заменяются знаками подчеркивания.
К названиям переменных применяются следующие правила:
- Название переменной должно передавать намерения программиста
- Название переменной должно сообщить, почему эта переменная существует, что она делает и как используется
- Название переменной не должно быть коротким
- В названии переменной не должен использоваться тип данных. Исключение составляет Map ( $typesMap , $statesMap ), т.к. в ином случае его не отличить от массива с данными.
- Если переменная хранит признак, то он должен быть включен в название ( unpaidProject )
- Переменные, отражающие свойства объекта, должны включать название объекта ( userIsAdmin , messageIsSend , figureCanBePainted , projectName )
- Переменные и свойства объекта должны являться существительными и называться так, чтобы они правильно читались при использовании, а не при инициализации
Плохо:
$object->expire_at $object->setExpireAt($date); $object->getExpireAt();$object->expiration_date; $object->setExpirationDate($date); $object->getExpirationDate();if ($project->isInvalid()) < // . >if ($project->isNotValid()) < // . >if ($accessManager->isAccessDenied()) < // . >if (!$project->isValid()) < // . >if (!$accessManager->isAccessAllowed()) < // . >if ($accessManager->canAccess()) < // . >Правила оформления кода
В первую очередь ставится пространство имен (namespace), которое используется (если есть). Далее пишется конструкции использования классов ( use ). В случае использования нескольких
классов одного пространства имен происходит группировка с помощью конструкции <. >. Далее идет объявление класса.
Фигурные скобки ставятся на той же строке и разделяются пробелом.
- Внутри не разделяются пробелом.
- Снаружи разделяются пробелами управляющие конструкции
- После названия метода/функции — пробел не ставится.
Каждая переменная должна быть объявлена на новой строке.
Условия и служебные вызовы методов разделяются переносом строки, переменные и работа с ними переносами строк не разделяются.
Внутри условий и циклов дополнительный перенос на новую строку не ставится.
Содержимое класса разделяется сверху одной пустой строкой.
class InterfaceType < private $property = 'myProp'; public function getProperty():string < return $this->property; > >Перед возвращаемым значением( return ) обязательно ставится перенос строки, если метод не состоит из единственной строки.
Если условие является большим, то обязательно выделить его в одно или несколько смысловых выражений и использовать его (их) в условии.
if (IS_REGISTRATOR() && (($params.status === 'W' || $params.status === 'D' || $params.status === 'A') && $params.remark && (($params.subres_level == 0 && ($user_info->selected_title->tid == $params.boss || $user_info->selected_title->tid == $doc_signer_tid || !$params.usertid) || $params.subres_level > 0 && $user_info->selected_title->tid == $params.usertid)))
$docIsInWorkAcceptOrDraft = . ; $bossHasSignerPriviledge = . ; $userCanSign = . ; if ($docIsInWorkAcceptOrDraft && $bossHasSignerPriviledge && $userCanSign) < // . >Комментирование кода
В общем случае комментарии запрещены (НЕ «всегда»). Любой участок кода, который необходимо выделить или прокомментировать, надо выносить в отдельный метод.
Комментарии должны быть расположены перед объявлением классов, переменных и методов и быть оформлены в соответствии с PHPDoc. Комментарий перед классом должен содержать описание бизнес-логики и отражать его назначение с приведением примеров использования.
Однострочный комментарии обозначаются символами // , а многострочный /*. */ .
Готовые алгоритмы, взятые из внешнего источника, должны быть помечены ссылкой на источник.
Правила написания кода
Везде, где имеет смысл, должнно быть прописано declare(strict_types=1);
В функциях/методах вместо отсутствующего скалярного значения используется null . 0 и пустую строку нельзя использовать в качестве показателя отсутствия значения.
function sendEmail(string $title, string $message = null, string $date = null): void < // . >// сообщение не было передано $object->sendEmail('Title', null, '2017-01-01'); // было передано пустое сообщение $object->sendEmail('Title', '', '2017-01-01');Нельзя изменять переменные, которые передаются в метод на вход (исключение — если эта переменная объект).
Нельзя нескольким переменным присваивать одно и то же значение. Для проверки наличия ключа в ассоциативном массиве используется array_key_exists , а не isset . Нельзя смешивать в массиве строковые и числовые ключи. Нельзя сортировать ассоциативные массивы.
Строки обрамляются одинарными кавычками. Двойные кавычки используются только, если:
- Внутри строки должны быть одинарные кавычки
- Внутри строки используется подстановка переменных
- Внутри строки используются спец. символы \n , \r , \t и т.д.
Вместо лишней конкатенации используем подстановку переменных в двойных кавычках
В методах должна быть использована максимально возможная типизация, включая тип возвращаемого значения( : type ). Все параметры и их типы должны быть описаны в объявлении метода либо в PHPDoc. Методы названия, которых начинаются c check и validate , должны выбрасывать исключения и не возвращать значения.
Все методы класса по умолчанию должны быть private . Если метод используется наследниками класса, то он объявляется protected . Если используется сторонними классами, тогда public .
Если метод может вернуть null , то желательно реализовать шаблон проектирования Null object, или выбросить исключение, или вернуть объект особого случая (пример: пустой массив).
При возврате из метода данных типа json — недопустимо писать return true , всегда использовать конструкцию return [‘success’ => [‘message’ => ‘. ‘]] или [‘error’ => [‘message’ => ‘. ‘]] . message приведен для примера, можно использовать любые ключи в неограниченном количестве.
Метод должен явно отличать нормальные ситуации от исключительных.
По умолчанию тексты исключений не должны показываться пользователю. Они предназначены для логирования и отладки. Текст исключения можно показать пользователю, если оно явно для этого предназначено.
В условном операторе должно проверяться исключительно boolean значение. В сравнении не boolean переменных используется строгое сравнение с приведением типа ( === ), автоматическое приведение и нестрогое сравнение не используются.
if ($user) < // . >if ($request->postData('amount') == 100) < // . >if (!$request->postData('amount')) < // . >if ($user === null) < // $user является типом object // . >if ((int)$request->postData('amount') === 100) < // . >if ($booking->comment === '') < // . >При использовании в условном выражении одновременно операторов И и ИЛИ обязательно выделять приоритет скобками.