Code Style (based on Zend Code Demarcation)

Соглашение по именованию

Соглашение по именованию аналогично соглашению по именованию Zend Framework с некоторыми дополнениями.

Стиль написания кода

Настройки CodeStyle и авторевакторинга для импорта

Обрамление PHP-кода

PHP-код должен всегда обрамляться сокращёнными PHP-тегами:

<?

?>

Строки

Строковые литералы

Когда строка является литеральной (не содержит подстановок переменных), для ее обрамления должны использоваться апострофы или "одинарные кавычки": $a = 'Example String';

Строковые литералы, содержащие апострофы

Когда строка литералов сама содержит апострофы, разрешается для обрамления строки использовать "двойные кавычки". Это особенно актуально для SQL-запросов:

$sql = "SELECT 'id', 'name' from 'people' WHERE 'name'='Fred' OR 'name'='Susan'";

Синтаксис выше является более предпочтительным, чем экранирование апострофов.

Подстановка переменных

Подстановка переменных разрешается с использованием нижеприведенных форм:

`$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";`

Для надежности следующая форма не допустима:

$greeting = "Hello ${name}, welcome back!";

Конкатенация строк

Строки должны объединятся с помощью оператора ".". Пробел должен всегда добавляться до и после оператора "." для улучшения читабельности, при использовании echo допустимо не конкатенировать строки, а выводить через запятую:

$company = 'Med' . ' ' . 'About' . ' ' . 'Me';

Когда производится конкатенация строк с помощью оператора ".", разрешается разрывать выражение на несколько строк для улучшения читабельности. В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы оператор "." был выровнен под оператором "=":

$sql = "SELECT id, name FROM people "
     . "WHERE name = 'Susan' "
     . "ORDER BY name ASC ";

Массивы

Массивы необходимо задавать конструкцией [] вместо array(), кроме тех случаев, где это явно не рекомендуется:

• проект на PHP 5.3 и младше без возможности миграции на старшие версии;
• массив описывает параметры компонента Битрикс (также аналогичные места, связанные с парсером Bitrix). Актуально только для вызова компонентов, чьи настройки должны редактироваться через визуальный редактор.

Массивы с числовыми индексами

Отрицательные числа в качестве индексов запрещены.

Хотя индекс массива может начинаться с любого неотрицательного числа, но не приветствуется и не рекомендуется начинать индексирование не с 0.

Когда определяется индексированный массив с помощью конструкции [], завершающий пробел должен быть добавлен после каждой запятой для улучшения читабельности:

$sampleArray = [1, 2, 3, 'Med', 'Me'];

Также разрешается определять многострочные индексированные массивы, используя конструкцию "[]". В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы начало каждой строки было выравнено как показано ниже:

$sampleArray = array[
     1,
     2,
     3,
     'Med',
     'About',
     $a,
     56.44,
     $d
];

Ассоциативные массивы

Когда определяется ассоциативный массив с помощью конструкции [], необходимо разделение выражения на несколько строк. В этом случае, каждая следующая строка должна быть дополнена с помощью пробелов так, чтобы и ключи и значения были выровнены, "=>" должен быть выравнен пробелами относительно остальных:

$sampleArray = [
     'firstKey'  => 'firstValue',
     'secondKey' => 'secondValue'
];

Классы

Определение класса

• Классы должны быть именованы согласно схеме именования Zend Framework.
• Фигурная скобка всегда пишется на следующей строке под именем класса.
• Каждый класс должен иметь блок документации (doc-блок) в соответствии со стандартом PHPDocumentor.
• Код внутри класса должен иметь отступ в четыре пробела.
• Только один класс разрешен внутри одного PHP-файла.

Это пример допустимого определения класса:

/**
 * Doc-блок здесь
 */
 class SampleClass
 {
    // содержимое класса должно быть
    // с отступом в четыре пробела
 }

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

class SampleClass extends FooAbstract implements BarInterface
 {
 }

Если в результате такого объявления, длина строки превышает максимальную длину строки, сделайте перенос перед ключевыми словами "extends" и/или "implements" и сделайте отступ в один уровень.

class SampleClass
    extends FooAbstract
    implements BarInterface
    {
    }

Если класс реализует несколько интерфейсов и объявление превышает максимальную длину строки - сделайте перенос после запятой, разделяющей интерфейсы, и выровняйте их имена пробелами:

class SampleClass
    implements BarInterface,
               BazInterface
     {
     }

Переменные-члены классов

• Переменные-члены классов должны быть именованы согласно схеме именования Zend Framework.
• Любые переменные, определенные в классе, должны быть определены в начале класса, до определения любого метода.
• Ключевое слово var не разрешено. Члены класса должны всегда определять их область видимости, используя ключевое слово private, protected или public. К публичным переменным-членам класса доступ напрямую разрешен, но не приветствуется в пользу методов доступа (set & get).

Функции и методы

Определение функций и методов

• Функции должны должны быть именованы согласно схеме именования Zend Framework.
• Функции внутри классов должны всегда определять свою область видимости с помощью одного из префиксов private, protected или public.
• Фигурная скобка после названия функции всегда пишется на той же строке, что и имя функции. Отделяется одним пробелом. Пробелы между именем функции и круглой скобкой для аргументов не допускаются.

Это пример допустимого определения метода:

/**
 * Doc-блок здесь
 */
 class Foo
 {
    /**
    * Doc-блок здесь
    */
    public function bar() {
        // содержимое класса должно быть
             // с отступом в четыре пробела
    }
 }

Передача по ссылке допустима только в определениях функций:

/**
  * Doc-блок здесь
  */
  class Foo
  {
    /**
    * Doc-блок здесь
    */
    public function bar(&$baz) {}
  }

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

Использование функций и методов

• Аргументы функции разделяются одним завершающим пробелом после каждой запятой. Это пример допустимого вызова функции для функции, которая принимает три аргумента:
• threeArguments(1, 2, 3);
• Передача по ссылке во время вызова запрещена. Смотрите секцию определения функций для правильного способа передачи аргументов функции по ссылке.
• Для функций, чьи аргументы допускают массив, вызов функции может включать конструкцию "[]" и может быть разделено на несколько строк для улучшения читабельности. В этом случае применим стандарт описания массивов.

Управляющие структуры If / Else / Elseif; циклы For / Foreach / While

• Полный синтаксис (endif; endforeach;) СТРОГО ЗАПРЕЩЁН.
• Управляющие структуры, основанные на конструкциях if и elseif, должны иметь один пробел до открывающей круглой скобки условия, и один пробел после закрывающей круглой скобки.
• Внутри выражения условия между круглыми скобками операторы должны разделяться пробелами для читабельности. Внутренние скобки приветствуются для улучшения логической группировки больших условий.
• Открывающаяся фигурная скобка пишется на той же строке, что и условие. Закрывающаяся фигурная скобка пишется на отдельной строке. Все содержимое между скобками пишется с отступом в четыре пробела.

if ($a != 2) {
    $a = 2;
 }

• Для всех "if", "elseif" или "else" выражений необходимо использовать фигурные скобки.