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

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

2. Строки

3. Ключевые слова

4. Массивы

5. Классы

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

7. Управляющие структуры

8. Комментарии

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

<?php
 
?>

От экранирования кавычек в строках лучше избавляться, т.е. если в строке нет одинарных кавычек, то для ее обрамления используются одинарные кавычки:

$sample = 'world';

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

$sample = "world's";

Использовать heredoc-синтаксис запрещено.

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

$sample = 'hello ' . 'world';
$sample = $msg . "world's";

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

$query = 'SELECT `a`.`name`, `a`.`id` FROM `sys_access_registry` `r`'
       . 'INNER JOIN `sys_classes_sections` `cs` ON `cs`.`id` = `r`.`class_section_id`'
       . 'INNER JOIN `sys_classes_actions` `ca` ON `ca`.`class_id` = `cs`.`class_id`'
       . 'INNER JOIN `sys_actions` `a` ON `a`.`id` = `ca`.`action_id`'
       . 'WHERE `r`.`obj_id` = ' . $this->obj_id;

Допустим также и такой способ разрыва, например, для SQL запроса:

$qry = 'SELECT `a`.`name`, `a`.`id` FROM `sys_access_registry` `r`
         INNER JOIN `sys_classes_sections` `cs` ON `cs`.`id` = `r`.`class_section_id`
          INNER JOIN `sys_classes_actions` `ca` ON `ca`.`class_id` = `cs`.`class_id`
           INNER JOIN `sys_actions` `a` ON `a`.`id` = `ca`.`action_id`
            WHERE `r`.`obj_id` = ' . $this->obj_id;

Ключевые слова должны быть строго в нижнем регистре:

true, false, null, new, class, function, ...

Каждый элемент массива должен быть отделен от другого пробелом после запятой:

$sample = array(1);
$sample = array(1, 2, 'hello', "world's");
$sample = array(1, 2, 'hello', "world's",
                'cms', $a, $b, $c,
                $f, 'value', null, -1);

При указании ключа перед и после '=>' необходимо поставить пробел:

$sample = array('key' => 'value');

Фигурная скобка всегда пишется на следующей строке под именем класса. В строке с фигурной скобкой не должно быть других печатных символов.

Каждый класс должен иметь блок комментариев в соответствии со стандартом PHPDocumentor.

Только один класс разрешен внутри одного PHP-файла.

Размещение дополнительно кода в файле с классом разрешено, но не приветствуется. В таких файлах, две пустые строки должны разделять класс и дополнительный PHP-код.

Пример класса:

/**
 * Блок комментариев
 */
class sample
{
    // содержимое класса
}

Любые переменные, определенные в классе, должны быть определены в начале класса, до определения любого метода.

Ключевое слово var не разрешено. Члены класса должны всегда определять их область видимости, используя ключевое слово private, protected или public. Доступ к переменным-членам класса напрямую используя префикс public разрешено, но не приветствуется в пользу методов.

Методы должны всегда определять свою область видимости с помощью одного из префиксов private, protected или public.

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

Функции в глобальной области видимости крайне не приветствуются.

Пример определения метода:

/**
 * Блок комментариев
 */
class Foo
{
    /**
     * Блок комментариев
     */
    public function bar($arg, $name, $value = 'default')
    {
        // содержимое класса
    }
}

Возвращаемое значение не должно обрамляться в круглые скобки:

return $this->bar; // ПРАВИЛЬНО
return($this->bar); // НЕПРАВИЛЬНО

Управляющие структуры, основанные на конструкциях if и else(if), должны иметь один пробел до открывающей круглой скобки условия, и один пробел после закрывающей круглой скобки.

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

Открывающаяся фигурная скобка пишется на той же строке, что и условие. Закрывающаяся фигурная скобка пишется на отдельной строке.

if ($a != 2) {
    $a = 2;
}
 
if ($a != 2 && $b == 'value') {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}

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

Управляющие структуры написанные с использованием "switch" конструкции должны иметь один пробел до открывающей круглой скобки условного выражения, и также один пробел после закрывающей круглой скобки.

Содержимое каждого "case" выражения должно писаться с отступом в дополнительные четыре пробела.

switch ($value) {
    case 1:
        $a = 'b';
        break;
 
    case 2:
        break;
 
    default:
        break;
}

Все блоки комментариев должны быть совместимы с форматом phpDocumentor. Для получения дополнительной информации смотрите: http://phpdoc.org/

Подходят комментарии в стилях C (/* */) и C++ (//). Первые используются в определении классов, методов, функций и т.д., а вторые внутри методов, функций и в глобальной видимости. Использование комментариев в стиле Perl/shell (#) не допускается.

Все PHP-файлы должны содержать минимальный блок комментариев в качестве заголовка:

/**
 * $URL$
 *
 * MZZ Content Management System (c) 2005-2008
 * Website : http://www.mzz.ru
 *
 * This program is free software and released under
 * the GNU Lesser General Public License (See /docs/LGPL.txt).
 *
 * @link http://www.mzz.ru
 * @version $Id$
 */