PSR-2. Руководство по стилю кода.

Павел Литовский PSR

Данная статья, это авторский перевод, описания стандарта. С оригиналом описания Вы можете ознакомиться здесь. 

Данное руководство расширяет и дополняет рекомендации, указанные в PSR-1 (основной стандарт написания кода).

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

Данные правила были получены из общих черт проектов, написанных различными членами PHP-FIG. Когда различные авторы работают с различными проектами, то это помогает установить единый набор правил для использования во всех этих проектах. Таким образом, польза данного руководства, заключается не в установке самих правил, а в их максимально широком распространении и использовании.

Встречающиеся ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «СЛЕДУЕТ», «НЕ СЛЕДУЕТ», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ОПЦИОНАЛЬНО» в данном стандарте интерпретируются как описано в документе RFC 2119.

1. Общий обзор. 

  • Код ДОЛЖЕН следовать руководству по стилю кодирования PSR-1.
  • В коде ДОЛЖНЫ использоваться 4 пробела для отступа, но не знак табуляции.
  • НЕ ДОЛЖНО быть жесткого ограничения длины строки, при этом СЛЕДУЕТ стремиться соблюдать длину строки не более 80 символов, в нужных случаях рекомендуемым лимитом является длина не более 120 символов.
  • ДОЛЖНА быть одна пустая строка после объявления пространства имен, ключевое слово [cci lang=»php»]namespace [/cci], также ДОЛЖНА быть одна пустая строка после блока импорта/создания псевдонима имени с помощью оператора [cci lang=»php»]use [/cci].
  • Открывающая скобка для тела класса { ДОЛЖНА располагаться на следующей строке после объявления класса, а закрывающая скобка } ДОЛЖНА находиться на следующей строке после тела класса.
  • Открывающая скобка { для методов ДОЛЖНА располагаться на следующей строке после объявления функции, а закрывающая скобка } должна находиться на следующей строке после тела метода.
  • Область видимости, задаваемая ключевыми словами [cci lang=»php»]public, protected, private [/cci], ДОЛЖНА быть обязательно указана для всех  свойств и методов. Ключевые слова [cci lang=»php»]abstract [/cci] и [cci lang=»php»]final [/cci] ДОЛЖНЫ быть объявлены перед объявлением области видимости. Ключевое слово [cci lang=»php»]static [/cci]  также ДОЛЖНО располагаться после объявления области видимости.
  • После ключевых слов в управляющих конструкциях (if, while, for и т.д.) обязательно ДОЛЖЕН быть один символ пробела, а вот после вызова метода или вызова функции пробела быть НЕ ДОЛЖНО.
  • Для управляющих конструкций открывающая скобка { ДОЛЖНА располагаться в той же строке, а вот закрывающая скобка } ДОЛЖНА идти на следующей строке после тела управляющей конструкции.
  • Открывающая круглая скобка ( в управляющих конструкциях НЕ ДОЛЖНА иметь символ пробела после себя, и также символа пробела НЕ ДОЛЖНО быть перед закрывающей круглой скобкой ).

1.1. Пример.

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

[CCE lang=»php»]
$b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2 $arg3);
}
}

final public static function bar()
{
// тело метода
}
}
[/CCE] 

2. Общие рекомендации. 

Основной стандарт стиля кода.

Код ДОЛЖЕН следовать всем правилам описанным в стандарте PSR-1

2.2. Файлы.

Все PHP файлы ДОЛЖНЫ использовать в конце строки символ переноса строки Unix LF (linefeed).

Все PHP файлы ДОЛЖНЫ оканчиваться одной пустой строкой.

Если файл содержит только PHP код, то в конце НЕ ДОЛЖНО быть закрывающего тега [cci]?>[/cci].

2.3. Строки.

НЕ ДОЛЖНО быть строгого ограничения на длину строки.

Допустимый предел длины строки ДОЛЖЕН быть не более 120 символов. Автоматические системы проверки стиля кода ДОЛЖНЫ предупреждать об этом, но НЕ ДОЛЖНЫ выдавать ошибку при таком мягком ограничении.

Строки НЕ ДОЛЖНЫ быть длиннее, чем 80 символов. Если длина строки больше, то СЛЕДУЕТ ее разделить на несколько следующих друг за другом строк таким образом, чтобы длина каждой не превышала 80 символов.

Непустые строки НЕ ДОЛЖНЫ завершаться символами пробелов.

Пустые строки МОГУТ быть добавлены для улучшения читабельности кода, а также для визуального указания логически связанных участков кода.

НЕ ДОЛЖНО быть более одного оператора в строке.

2.4. Отступы.

В коде для отступов ДОЛЖНЫ использовать 4 символа пробела,
но НЕ ДОЛЖЕН применяться символ табуляции.

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

2.5. Ключевые слова True/False/Null.

Ключевые слова ЯП PHP ДОЛЖНЫ использоваться в нижнем регистре.

Константы ЯП PHP: [cci]true[/cci], [cci]false[/cci] и [cci]null[/cci] ДОЛЖНЫ использоваться в нижнем регистре.

3. Пространства имен и блока с use (импорт/объявление псевдонимов).

Если имеется блок объявления пространства имен [cci]namespace[/cci], то после него обязательно ДОЛЖНА быть одна пустая строка.

Если в коде используется блок импорта/создания псевдонима имени с помощью [cci lang=»php»]use [/cci], то такой блок ДОЛЖЕН располагаться после объявления пространства имен [cci]namespace[/cci].

Для каждого блока импорта/создания псевдонима ДОЛЖНО каждый раз быть использовано одно ключевое слово [cci]use[/cci].

После всего блока [cci]use[/cci] ДОЛЖНА располагаться одна пустая строка.

Для примера:
[cce lang=»php»]

4. Классы, Свойства и Методы.

Под термином «класс» здесь подразумеваются все классы, интерфейсы и трейты.

4.1. Ключевые слова Extends и Implements.

Ключевые слова [cci]extends[/cci] и [cci]implements[/cci] ДОЛЖНЫ располагаться в той же строке, что и имя класса.

Открывающая скобка для тела класса { ДОЛЖНА располагаться на следующей строке после объявления класса, а закрывающая скобка } ДОЛЖНА находиться на следующей строке после тела класса.

[cce lang=»php»]
Списки реализуемых интерфейсов после ключевого слова [cci]implements[/cci] МОГУТ быть разделены на несколько строк, где каждые последующие строки имеют одинаковые отступы. При этом первый элемент списка ДОЛЖЕН быть на новой строке, и каждый последующий интерфейс списка ДОЛЖЕН быть на отдельной строке.

[cce lang=»php»]
4.2. Свойства.

Область видимости, задаваемая при помощи ключевых слов [cci]private, public, protected[/cci], ДОЛЖНА быть указана для всех свойств класса.

Ключевое слово [cci]var[/cci] НЕ ДОЛЖНО использоваться при объявлении свойства.

В одном выражении НЕ ДОЛЖНО быть более одного свойства.

В целях визуального указания области видимости свойства, которое является защищенным ([cci]protected[/cci]) или приватным ([cci]pivate[/cci]), в имени свойства НЕ СЛЕДУЕТ использовать префикс в виде одного символа подчеркивания.

При объявлении свойств класса, придерживайтесь ниже следующего кода:

[cce lang=»php»]
4.3. Методы.

Область видимости ДОЛЖНА указываться при объявлении всех методов.

Для указания, что метод имеет область видимости proetcted или private, НЕ СЛЕДУЕТ в имени метода использовать префикс в виде одного символа подчеркивания.

При объявлении метода, после имени метода НЕ ДОЛЖНЫ иметься символы пробелов. После имени метода сразу располагается круглая открывающая скобка, при этом НЕ ДОЛЖНО быть символов пробела после открывающий круглой скобки, и НЕ ДОЛЖНО быть символов пробела перед закрывающей круглой скобкой. Также открывающая скобка для тела класса { ДОЛЖНА располагаться на следующей строке после объявления класса, а закрывающая скобка } ДОЛЖНА находиться на следующей строке после тела класса.

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

[cce lang=»php»]
4.4. Аргументы методов.

В списке аргументов метода НЕ ДОЛЖНО быть символа пробела перед запятой, но при этом ДОЛЖЕН быть символ пробела после каждой запятой.

Аргументы метода у которых имеются значения по умолчанию ДОЛЖНЫ идти в конце списка аргументов.

[cce lang=»php»]
Список аргументов МОЖНО разделить на несколько строк, таким образом, чтобы каждые последующие строки имели одинаковый отступ. При этом первый аргумент списка ДОЛЖЕН располагаться на новой строке, и каждый последующий аргумент также ДОЛЖЕН находиться на новой отдельной строке.

Когда список аргументов разбивается на несколько строк, то закрывающая круглая скобка ) и открывающая фигурная скобка { ДОЛЖНЫ быть размещены вместе на одной отдельной строке с одним пробелом между ними.

[cce lang=»php»]
4.5. Ключевые слова abstract, final и static.

Когда используются ключевые слова [cci]abstract[/cci] и [cci]final[/cci], то они должны располагаться перед объявлением области видимости (public, protected, private).

Когда используется ключевое слово [cci]static[/cci], то оно ДОЛЖНО располагаться после объявления области видимости.

[cce lang=»php»]
4.6. Вызовы функций и методов.

Когда производится вызов функции или метода, то НЕ ДОЛЖНО быть символа пробела между именем функции или метода и открывающей круглой скобкой, НЕ ДОЛЖНО быть пробела и после открывающей круглой скобки, также НЕ ДОЛЖНО быть символа пробела перед закрывающей круглой скобкой. В списке аргументов НЕ ДОЛЖНО быть символа пробела перед символами запятой, но при этом обязательно ДОЛЖЕН быть пробел после каждой запятой.

[cce lang=»php»]
bar($arg1);
Foo::bar($arg2, $arg3);
[/cce]

Список аргументов МОЖНО разделить на несколько строк, таким образом, чтобы каждые последующие строки имели одинаковый отступ. При этом каждый аргумент списка ДОЛЖЕН располагаться на новой отдельной строке

[cce lang=»php»]
bar(
$longArgment,
$longerArgument,
$muchLongerArgument
);
[/cce]

5. Управляющие конструкции.

Общие требования к стилю управляющих конструкций:

  • ДОЛЖЕН быть один символ пробела после ключевого слова управляющей конструкции.
  • НЕ ДОЛЖНО быть символа пробела после открывающей круглой скобки.
  • НЕ ДОЛЖНО быть символа пробела перед закрывающей круглой скобкой.
  • ДОЛЖЕН быть один пробел между закрывающей круглой и открывающей фигурной скобками.
  • Код в теле управляющей конструкции ДОЛЖЕН иметь один отступ.
  • Закрывающая фигурная скобка } должна располагаться на следующей строке после тела управляющей конструкции.

Также тело каждой управляющей конструкции ДОЛЖНО быть заключено в фигурные скобки. Это стандартизирует, как выглядят управляющие конструкции, и уменьшает вероятность возникновения ошибок по мере добавления новых строк в тело конструкций.

5.1. if, elseif и else.

Конструкция [cci]if[/cci] выглядит как в примере кода ниже. Обратите внимание на размещение круглых скобок, пробелов и фигурных скобок, а также, что [cci]else[/cci] и [cci]elseif[/cci] находятся на той же линии, что и заключительная фигурная скобка из предыдущего тела управляющей конструкции.

[cce lang=»php»]
Ключевое слово [cci]elseif[/cci] СЛЕДУЕТ использовать вместо раздельного [cci]else if[/cci], таким образом все ключевые слова управляющей конструкции будут выглядеть в одно слово.

5.2. switch, case.

Конструкция [cci]switch[/cci] выглядит, как в примере кода ниже. Обратите внимание на размещение круглых скобок, пробелов и фигурных скобок. Ключевое слово [cci]case[/cci] ДОЛЖНО иметь один отступ по сравнению с [cci]case[/case], а ключевое слово [cci]break[/cci] (или другое ключевое слово, имеющее эффект выхода из управляющей конструкции) ДОЛЖНО располагаться с тем же отступом, что и другие строки внутри [cci]case[/cci]. Также, когда намеренно не используется выход из непустого [cci]case[/cci] управляющей конструкции, то для таких ситуаций ДОЛЖЕН быть использован комментарий [cci]// no break[/cci].

[cce lang=»php»]
5.3. while, do while.

Конструкция [cci]while[/cci] выглядит как в примере кода ниже. Обратите внимание на размещение круглых скобок, пробелов и фигурных скобок.

[cce lang=»php»]
Аналогично, конструкция [cci]do while[/cci] выглядит как в примере кода ниже. Обратите внимание на размещение круглых скобок, пробелов и фигурных скобок.

[cce lang=»php»]
5.5. foreach.

Конструкция [cci]foreach[/cci] выглядит как в примере кода ниже. Обратите внимание на размещение круглых скобок, пробелов и фигурных скобок.

[cce lang=»php»]
$value) {
// тело управляющей конструкции
}
[/cce]

5.6. try, catch.

Блок [cci]try catch[/cci] выглядит как в примере кода ниже. Обратите внимание на размещение круглых скобок, пробелов и фигурных скобок.

[cce lang=»php»]
6. Замыкания.

Замыкания ДОЛЖНЫ объявляться с использованием символа пробела после ключевого слова [cci]function[/cci], и символами пробелов до и после ключевого слова [cci]use[/cci].

Открывающая фигурная скобка ДОЛЖНА располагаться на той же строке, а закрывающая фигурная скобка ДОЛЖНА располагаться на следующей строке после тела функции.

НЕ ДОЛЖНО быть символа пробела после открывающей круглой скобки для списка аргументов или списка переменных, а также НЕ ДОЛЖНО быть пробелов перед закрывающей круглой скобкой списка аргументов или списка переменных.

В списке аргументов и списке переменных НЕ ДОЛЖЕН быть символ пробела перед каждой запятой, но ДОЛЖЕН быть один символ пробела после каждой запятой.

Замыкаемые аргументы, имеющие значения по умолчанию ДОЛЖНЫ располагаться в конце списка аргументов.

Объявление замыкания выглядит как в примере кода ниже. Обратите внимание на размещение круглых скобок, пробелов и фигурных скобок:

[cce lang=»php»]
Список аргументов и переменных МОЖНО разделить на несколько строк, таким образом, чтобы каждые последующие строки имели одинаковый отступ. При этом каждый аргумент списка ДОЛЖЕН располагаться на новой отдельной строке

Когда оканчивается список аргументов или переменных, разбитый на несколько строк, то закрывающая круглая скобка и открывающая фигурная скобка ДОЛЖНЫ быть размещены вместе на одной строке с одним пробелом между ними.

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

[cce lang=»php»]
Обратите внимание, что правила форматирования также применяются, когда замыкание используется непосредственно в вызове функции или метода в качестве аргумента.

[cce lang=»php»]
bar(
$arg1,
function ($arg2) use ($var1) {
// тело функции
},
$arg3
);
[/cce]

7. Заключение.

Существует много элементов стиля и практики, преднамеренно не освещенных в этой рекомендации. К ним относятся, но не ограничиваются:

  • Объявление глобальных переменных и глобальных констант.
  • Объявление функций.
  • Операторы и присваивание.
  • Межстрочное выравнивание.
  • Блоки комментариев и документации.
  • Префиксы и суффиксы в именах классов.
  • Применение лучших практик.

Будущие рекомендации МОГУТ пересматривать и расширять это руководство для рассмотрения различных элементов стиля и хорошей практики.