Стандарты оформления кода php
Стандарты кодирования PHP (PSR)
Группа взаимодействия фреймворков (PHP-FIG) окончательно приняла рекомендации к стандартам оформления кода на PHP.
Оригинальные тексты можно посмотреть на гитхабе.
PSR-0: требования к названиям классов
и неймспейсов для универсального автозагрузчика.
Полное имя класса должно быть вида `\ \( \)* `
PSR-1: Основные стандарты кодирования
Секция описывает общие правила оформления кода:
— Использование только тэгов
namespace Vendor\Package ;
use FooInterface ;
use BarClass as Bar ;
use OtherVendor\OtherPackage\BazClass ;
final public static function bar ( )
<
// method body
>
>
В голосовании по принятию стандартов участвовали разработчики таких проектов, как
Agavi
CakePHP, CakePHP 2
Chisimba, C4
Composer, Packagist
Doctrine, Doctrine2, et al.
Drupal
eZ Publish
FLOW3
Joomla
Lithium
PEAR, PEAR2
phpBB
PPI, PPI2
Propel, Propel 2
SabreDAV
Solar Framework, Aura Project
Symfony, Symfony2
Zend Framework, Zend Framework 2
Zikula
Соответствование требованием конкретных проектов можно посмотреть на
гугл докс
Но, сдавать код в общий проект будьте добры по тем правилам, которые установлены для всех (или в организации, где вы работаете). Стандарт на то и стандарт, чтобы любой разработчик мог открыть код и начать с ним работать, а не тратить время на его форматирование под себя.
PHP Code Style Conventions
В данной статье рассматривается подход к написанию и оформлению PHP кода. Нижеизложенные моменты были сформированы путем анализа существующих подходов компаний и личного опыта.
Правила именования файлов и папок
Все названия для папок и файлов должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).
Папки
Если папка хранит в себе классы, которые относятся к пространству имен (namespace), то папка именуется в соответствии с названием пространства имен (namespace).
Файлы
Если файл является файлом класса, то именуется в соответствии с названием класса.
Правила именования пространств имен, классов, методов и переменных
Все названия должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).
Пространства имен
Названия пространств имен должны быть в нижнем регистре и состоять из одного слова. В случае необходимости именовать пространств имен более одного слова производится дробление на составные части, являющиеся вложенными пространствами имен.
Классы
Методы
К названиям методов применяются следующие правила:
Переменные
К названиям переменных применяются следующие правила:
Название переменной должно передавать намерения программиста
Название переменной должно сообщить, почему эта переменная существует, что она делает и как используется
Название переменной не должно быть коротким
Если переменная хранит признак, то он должен быть включен в название ( unpaidProject )
Переменные и свойства объекта должны являться существительными и называться так, чтобы они правильно читались при использовании, а не при инициализации
Плохо:
Хорошо:
Запрещены отрицательные логические названия
Плохо:
Хорошо:
Правила оформления кода
В первую очередь ставится пространство имен (namespace), которое используется (если есть). Далее пишется конструкции использования классов ( use ). В случае использования нескольких
классов одного пространства имен происходит группировка с помощью конструкции <. >. Далее идет объявление класса.
Фигурные скобки ставятся на той же строке и разделяются пробелом.
Каждая переменная должна быть объявлена на новой строке.
Условия и служебные вызовы методов разделяются переносом строки, переменные и работа с ними переносами строк не разделяются.
Внутри условий и циклов дополнительный перенос на новую строку не ставится.
Содержимое класса разделяется сверху одной пустой строкой.
Перед возвращаемым значением( return ) обязательно ставится перенос строки, если метод не состоит из единственной строки.
Если условие является большим, то обязательно выделить его в одно или несколько смысловых выражений и использовать его (их) в условии.
Плохо:
Хорошо:
Комментирование кода
В общем случае комментарии запрещены (НЕ «всегда»). Любой участок кода, который необходимо выделить или прокомментировать, надо выносить в отдельный метод.
Комментарии должны быть расположены перед объявлением классов, переменных и методов и быть оформлены в соответствии с PHPDoc. Комментарий перед классом должен содержать описание бизнес-логики и отражать его назначение с приведением примеров использования.
Готовые алгоритмы, взятые из внешнего источника, должны быть помечены ссылкой на источник.
Правила написания кода
Везде, где имеет смысл, должнно быть прописано declare(strict_types=1);
Нельзя изменять переменные, которые передаются в метод на вход (исключение — если эта переменная объект).
Строки обрамляются одинарными кавычками. Двойные кавычки используются только, если:
Вместо лишней конкатенации используем подстановку переменных в двойных кавычках
Метод должен явно отличать нормальные ситуации от исключительных.
По умолчанию тексты исключений не должны показываться пользователю. Они предназначены для логирования и отладки. Текст исключения можно показать пользователю, если оно явно для этого предназначено.
В условном операторе должно проверяться исключительно boolean значение. В сравнении не boolean переменных используется строгое сравнение с приведением типа ( === ), автоматическое приведение и нестрогое сравнение не используются.
При использовании в условном выражении одновременно операторов И и ИЛИ обязательно выделять приоритет скобками.
Правила оформления PHP-кода
1. Отступы
Отступы улучшают читабельность кода. Для их оформления используйте четыре пробела (но не знак табуляции).
2. Ключевые слова и константы true / false / null
3. Определение пространств имён и блоков импорта
4. Методы и аргументы
5. Вызовы методов и функций
6. Конструкции switch и case
7. Конструкции while и do while
Конструкцию while следует оформлять следующим образом. Между while и ( ставится пробел. После ( и до ) пробелов не должно быть. ) и < разделяются пробелом. Тело конструкции отделяется одним отступом (четыре пробела). >пишется на новой строке после тела конструкции.
Конструкция do while должна выглядеть так:
8. Конструкция for
Пример оформления конструкции for представлен ниже. Между for и ( ставится пробел. После ; ставится пробел. ) и < разделяются пробелом. Тело конструкции отделяется одним отступом (четыре пробела). >пишется на новой строке после тела конструкции.
9. Конструкция foreach
Конструкция foreach должна выглядеть следующим образом. Между foreach и ( ставится пробел. Перед и после => ставится пробел. ) и < разделяются пробелом. Тело конструкции отделяется одним отступом (четыре пробела). >пишется на новой строке после тела конструкции.
10. Конструкция try catch
Оформляйте конструкцию try catch следующим образом. Между try и < ставится пробел. >и следующий за ним catch находятся на одной строке. Между catch и ( ставится пробел. ) и < разделяются пробелом. Тело try и тело catch отделяется одним отступом (четыре пробела). >пишется на новой строке после тела конструкции.
Оформление кода PHP: стандарты и правила
Восемь общих правил
Существуют правила, которые подойдут для написания кода на любом языке программирования. Только следование им уже повысит качество вашего кода.
Правила кода PHP
На конец 2017 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.
Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.
Отступы
Правильное оформление кода PHP предполагает его простое визуальное восприятие. Оно достигается с помощью отступов и пробелов. Для формирования отступов используйте пробелы, а не знак табуляции. Каждую строку начинайте с четырех пробелов. Код должен идти лесенкой: раскрываться вправо, затем собираться обратно.
Запомните: один отступ = четыре пробела.
Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.
Правильно
Неправильно
Пробелы
Пустая строка
Правильно
Неправильно
Круглые скобки
Фигурные скобки
Аргументы
Оформляются двумя способами: в одну строку через запятую или в столбик. Аргументы на одной строке пишутся через запятую внутри круглых скобок. Пробел ставится только после запятой.
Правильно
Неправильно
При оформлении в столбик каждый аргумент пишется с новой строки и отделяется двойным отступом. Первая круглая скобка остается на строке вместе обозначением метода. Вторая круглая скобка выносится в отдельную строку вместе с открывающей фигурной скобкой. Между ними пробел.
Правильно
Неправильно
Конструкция switch case
Конструкцию делим на три уровня: switch, case, echo/break. Каждый уровень начинается с отступа. Таким образом, наш код визуально выглядит состоящим из трех столбцов.
Если в конструкции не используется break, поставьте // no break.
Правильно
Неправильно
Конструкция try catch
Тело try и тело catch отделяются одним отступом. Пробелы нужно поставить:
Catch и скобку > ставим на одну строку.
Правильно
Неправильно
Конструкция if, elseif, else
Правильно
Неправильно
Комментарии в коде
Чистый код должен быть правильно закомментирован. К сожалению, встречаются две крайности: подробное комментирование каждой строки и полное отсутствие комментариев. И то, и другое мешает в работе. Избыточное комментирование снижает восприятие кода, отвлекает от понимания его сути. Писать очевидные вещи — тратить свое и чужое время. Иногда из-за слишком подробных комментариев объем кода увеличивается в несколько раз. Закончив с кодом, посмотрите критически. Очевидные и банальные комментарии удалите.
Обратная сторона медали — отсутствие пояснений. Коды со сложной архитектурой, скриптами, с большой вложенностью требуют пометок. В этом случае комментарии помогут быстро ориентироваться в коде другим членам команды. Часто они помогают и самому разработчику кода. Главное — придерживаться золотой середины и комментировать только важные моменты.
Чек-лист «Инспекция кода»
Предлагаем чек-лист для самостоятельной проверки чистоты кода. Если вы будете инспектировать чужой код, помните, что программист — творческая профессия. А творческие люди обычно тяжело воспринимают критику. Будьте лояльней.
Желательно провести тестирование. Руководствуйтесь тремя принципами:
Дополнительную информацию по тестированию вы найдете в материале «Тестирование кода для чайников».
Заключение
Код — это не личный захламленный ящик с грудой бумаг. Правильный код — это картотека в Ленинской библиотеке. В нем все структурировано, задокументирована важная информация, есть связи с другими каталогами и библиотеками. Чистый код может разобрать и профи, и начинающий программист. С ним приятно работать, он характеризует уровень мастерства своего разработчика.
Старайтесь следовать принятым правилам, рекомендациям и стандартам. Думайте о тех, кто будет работать с ним после вас. Всегда пробуйте сделать код короче и эффективней. Напишите так, чтобы это понимал не только Бог.
Следование единым правилам упрощает работу программистов. Оформление кода PHP по одному стандарту помогает в командной работе и повышает уровень разработки. Понятие «качественный код» появилось не случайно, так же, как и анекдоты о неспособности спустя время прочитать даже собственный код. Понятный структурированный код сокращает время чтения, позволяет сразу приступить к поиску проблемы.
Восемь общих правил
Существуют правила, которые подойдут для написания кода на любом языке программирования. Только следование им уже повысит качество вашего кода.
Правила кода PHP
На конец 2017 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.
Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.
Отступы
Правильное оформление кода PHP предполагает его простое визуальное восприятие. Оно достигается с помощью отступов и пробелов. Для формирования отступов используйте пробелы, а не знак табуляции. Каждую строку начинайте с четырех пробелов. Код должен идти лесенкой: раскрываться вправо, затем собираться обратно.
Запомните: один отступ = четыре пробела.
Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.
Правильно
Неправильно
Пробелы
Пустая строка
Правильно
Неправильно
Круглые скобки
Фигурные скобки
Аргументы
Оформляются двумя способами: в одну строку через запятую или в столбик. Аргументы на одной строке пишутся через запятую внутри круглых скобок. Пробел ставится только после запятой.
Правильно
Неправильно
При оформлении в столбик каждый аргумент пишется с новой строки и отделяется двойным отступом. Первая круглая скобка остается на строке вместе обозначением метода. Вторая круглая скобка выносится в отдельную строку вместе с открывающей фигурной скобкой. Между ними пробел.
Правильно
Неправильно
Конструкция switch case
Конструкцию делим на три уровня: switch, case, echo/break. Каждый уровень начинается с отступа. Таким образом, наш код визуально выглядит состоящим из трех столбцов.
Если в конструкции не используется break, поставьте // no break.
Правильно
Неправильно
Конструкция try catch
Тело try и тело catch отделяются одним отступом. Пробелы нужно поставить:
Catch и скобку > ставим на одну строку.
Правильно
Неправильно
Конструкция if, elseif, else
Правильно
Неправильно
Комментарии в коде
Чистый код должен быть правильно закомментирован. К сожалению, встречаются две крайности: подробное комментирование каждой строки и полное отсутствие комментариев. И то, и другое мешает в работе. Избыточное комментирование снижает восприятие кода, отвлекает от понимания его сути. Писать очевидные вещи — тратить свое и чужое время. Иногда из-за слишком подробных комментариев объем кода увеличивается в несколько раз. Закончив с кодом, посмотрите критически. Очевидные и банальные комментарии удалите.
Обратная сторона медали — отсутствие пояснений. Коды со сложной архитектурой, скриптами, с большой вложенностью требуют пометок. В этом случае комментарии помогут быстро ориентироваться в коде другим членам команды. Часто они помогают и самому разработчику кода. Главное — придерживаться золотой середины и комментировать только важные моменты.
Чек-лист «Инспекция кода»
Предлагаем чек-лист для самостоятельной проверки чистоты кода. Если вы будете инспектировать чужой код, помните, что программист — творческая профессия. А творческие люди обычно тяжело воспринимают критику. Будьте лояльней.
Желательно провести тестирование. Руководствуйтесь тремя принципами:
Дополнительную информацию по тестированию вы найдете в материале «Тестирование кода для чайников».
Заключение
Код — это не личный захламленный ящик с грудой бумаг. Правильный код — это картотека в Ленинской библиотеке. В нем все структурировано, задокументирована важная информация, есть связи с другими каталогами и библиотеками. Чистый код может разобрать и профи, и начинающий программист. С ним приятно работать, он характеризует уровень мастерства своего разработчика.
Старайтесь следовать принятым правилам, рекомендациям и стандартам. Думайте о тех, кто будет работать с ним после вас. Всегда пробуйте сделать код короче и эффективней. Напишите так, чтобы это понимал не только Бог.
PSR Стандарты
PSR — Чуть больше, чем стиль оформления кода.
Как показала практика, многие PHP-разработчики знакомы с аббревиатурой PSR. Однако большинство все еще ограничены знанием, что PSR это стандарт оформления кода.
Ребята из PHP-FIG (PHP Framework Interop Group), группа концепций совместимости PHP, которые занимаются развитием PSR (PHP Standards Recommendations) шагнули далеко вперед. Поэтому давайте разберемся, что из себя представляет PSR…
За последние полгода мне пришлось провести множество собеседований на позицию Middle PHP-Developer.
Один из вопросов, который я задавал всем кандидатам, был:- «Знаете ли Вы, что такое PSR?»
Как оказалось, практически всем кандидатам была знакома эта аббревиатура. Однако пытаясь рассказать подробнее, почти все разработчики указывали в основном на то, что это стандарт оформления кода (code style). Только некоторые упоминали про PSR-4 автозагрузку (использует Composer) и PSR-3 Logger Interface (в сети очень много однородных статей про PSR-0-1-2-3-4).
Мне кажется это весьма странным, так как термин PSR существует достаточно давно (уже более 10 лет) и каждый год набирает все большую популярность. Поэтому, думаю, будет неплохо собрать все в кучу и сделать обзор PSR стандартов.
PHP-FIG и PSR
PHP-FIG (PHP Framework Interop Group) — организованная в 2009 году группа разработчиков, основная идея которой находить способы совместной работы, выделяя общие концепции в разработке проектов на PHP.
Проще говоря, ребята стараются выделить что-то общее между различными проектами на разных фреймворках и сформировать некие стандарты (рекомендации) для дальнейшего периспользования.
Участники PHP-FIG
ReactPHP, Composer, Laminas Project (переименованный Zend Framework), Yii framework, CakePHP, Slim, Joomla, Magento, Drupal, phpBB, phpDocumentor и другие.
PSR (PHP Standards Recommendations) — описывает общие концепции, которые уже были проверены и отработаны. Вероятно при создании PSR, группа PHP-FIG вдохновлялась Java Community Process, а первый стандарт был принят в 2010 году.
Список PSR стандартов расширяется новыми, а сами стандарты делятся на категории:
Автозагрузка, Интерфейсы, HTTP и Стиль кодирования,
каждому из которых присваивается определенный статус:
Принят, Устаревший, Черновик и Заброшенный.
Далее мы рассмотрим принятые PSR стандарты по категориям:
Автозагрузка
Разработчики, которые «недолго» работают с PHP, вероятно не знакомы с проблемами импорта классов, ведь есть пространства имен, а сейчас вообще трудно представить проект без менеджера зависимостей Composer, которой решает все вопросы с автозагрузкой классов.
Однако так было не всегда, пространства имен появились только в PHP 5.3 (это был 2009 год), а первый релиз Composer состоялся в марте 2012 года. Но вот сам PHP существует гораздо дольше, как Personal Home Page с 1995 года и как Hypertext Preprocessor с 1998 года, однако только PHP 5 включает «полноценную объектную модель», релиз которого был в июле 2004 года. Бородатым разработчикам того времени приходилось как-то сражаться со всеми возникшими проблемами при импорте классов.
Не самый плохой пример импорта классов на PHP 14-ти летней давности:
(Напишите в комментариях, если узнали где использовался данный подход).
В дополнение, оставлю ссылку на статью, которая подробно описывает работу с пространством имен, решенные проблемы и PSR-4.
Интерфейсы
PHP развивается, набирает все большую популярность, а его инфраструктура пополняется огромным количеством различных инструментов.
Появляются проблемы с изучением и переиспользованием однотипного функционала, а менеджер зависимостей может затянуть целую кучу несвязанных однотипных зависимостей. (тут JavaScript разработчик улыбнется).
Поэтому принято решение стандартизировать некоторые общие концепции:
Если Ваш проект нуждается в расширенном функционале, МОЖНО расширять данный интерфейс, но СЛЕДУЕТ сохранять совместимость с описанными в данном стандарте правилами. Это позволит сторонним библиотекам, применяемых при разработке приложения, использовать централизованную систему логирования.
Это привело к ситуации, когда многие библиотеки реализуют свои собственные системы кэширования с различными уровнями функциональности. Эти различия заставляют разработчиков изучать несколько систем, которые могут предоставлять или не предоставлять необходимую им функциональность. Кроме того, разработчики кеширующих библиотек сами сталкиваются с выбором между поддержкой только ограниченного числа платформ или созданием большого количества классов адаптеров.
Чтобы решить эти проблемы был принят общий стандарт для библиотек реализующих кэширование, он включает в себя несколько интерфейсов:
Пользователи НЕ ДОЛЖНЫ передавать контейнер в объект, чтобы объект мог получить свои собственные зависимости. Это означает, что контейнер используется в качестве Service Locator, который обычно не рекомендуется использовать.
Отсюда, возникает простой вопрос: «Как это вообще работает»?
На самом деле все просто, на помощь приходит паттерн Factory, который возьмет на себя задачу создания объекта. А вот сам класс фабрики уже может принимать ContainerInterface и передавать в создаваемый объект необходимые зависимости.
Поэтому был принят PSR-16. Этот более простой подход направлен на создание стандартизированного оптимизированного интерфейса для общих случаев.
В списке реализаций все тот-же Symfony Cache и Laminas Cache (бывший Zend).
Если речь идет о WEB-приложении, то не важно на сколько сложная в нем бизнес-логика, по факту оно делает всего 2 вещи — принимает Request и отдает Response. Это значит, что так или иначе, приходится реализовывать эти объекты у себя в проекте.
Пожалуй, одной из самых сложных задач, которая нередко возникает является переиспользование кода между различными проектами. Если хорошо абстрагированные участки бизнес логики, некоторые компоненты и модули перенести возможно (с минимальными затратами), то с переносом более высокого уровня фреймворков (например контроллеров) возникают сложности.
Группа PHP-FIG пытается исправить данную проблему и предоставляет стандарты абстракции над HTTP.
А более детальное описание с примерами можно разобрать в статье «PSR-7 в примерах».
Если не вдаваться во все тонкости, то по сути это возможность писать некие абстрактные контроллеры для последующего переиспользования между различными проектами.
PSR-7 не содержит рекомендации о том, как создавать HTTP-объекты. Это может приводить к трудностям при необходимости их создания внутри компонентов, которые не привязаны к конкретной реализации PSR-7.
Интерфейсы, описанные в этой спецификации, описывают методы, с помощью которых можно создавать PSR-7 объекты.
Это может сделать библиотеки более пригодными для повторного использования, так как уменьшает количество зависимостей и снижает вероятность конфликтов версий.
Также в спецификации указано, что HTTP-клиенты могут быть заменены согласно принципу подстановки Лисков. Это означает, что все клиенты ДОЛЖНЫ вести себя одинаково при отправке запроса.
Пример реализации PSR-18 можно увидеть в библиотеке Symfony HTTP-client.
Предложенная абстракция над HTTP — это весьма серьезная заявка на попытку реализовывать действительно переиспользуемые и не зависящие от конкретных библиотек и фреймворков полноценные решения.
На практике, конечно все на много сложнее и есть свои нюансы и подводные камни, однако PHP-FIG делает значительный шаг вперед в этом направлении.
Стиль кодирования
До появления стандартов стиля кодирования, каждый из разработчиков оформлял свой код по-разному: одни писали CLASSNAME, другие ClassName, а третьи Class_Name, вечный спор относительно табов и пробелов, а еще StudlyCaps vs сamelCase vs snake_case и так далее.
Цель следующих PSR стандартов уменьшить когнитивное искажение при чтении кода от разных авторов.