Coding Style - Стандарт кодирования на PHP

Стандарт оформления кода (стиль программирования) (англ. coding standards, coding convention или programming style)

Предлагаю, для ознакомления, часть текста документа, который я разработал для себя и своей команды. Основа взята с framework.zend.com/manual/ru/coding-standard.html, часть с PEAR и самая важная часть, из собственного опыта программирования. Я не жду единогласного признания т.к. каждый программист привык к тому к чему привык и, что-то другое для него будет не удобным и неправильным.

По запросу могу предоставить полный текст документа, всего 16 страниц выверенного текста.

Может размещу стандарты работы с БД MySQL, порядок работы с Git и руководство по написанию PHPUnit тестов.

Оглавление

• Формат файлов3
• Кодировка3
• Форматирование PHP-файлов3
• Общее3
• Отступы3
• Максимальная длина строки3
• Соглашения по именованию3
• Директории3
• Классы3
• Интерфейсы4
• Имена файлов4
• Функции и методы4
• Переменные и свойства5
• Константы5
• Стиль кодирования5
• Обрамление PHP-кода5
• Строки5
• Строковые литералы5
• Строковые литералы, содержащие апострофы6
• Подстановка переменных и конкатенация строк6
• SQL запросы6
• Массивы7
• Массивы с числовыми индексами7
• Ассоциативные массивы7
• Классы8
• Определение класса8
• Переменные-члены классов9
• Функции и методы9
• Определение функций и методов9
• Использование функций и методов11
• Вызовы функций и методов11
• Управляющие структуры12
• If / Else / Elseif12
• Switch13
• Комментарии14
• Встроенная документация14
• Файлы14
• Классы14
• Функции15

Формат файлов

Кодировка

Все файлы хранятся и редактируются в кодировке UTF-8.

Форматирование PHP-файлов

Общее

Всегда используйте <?php ?> вместо <? ?>для выделения PHP-кода. Это необходимо для обеспечения работы PEAR на разных операционных системах и с различными настройками.
Для файлов, содержащих только PHP-код, закрывающий тег ("?>") не разрешен. Он не требуется синтаксисом PHP и его пропуск предотвращает случайное включение в вывод конечных пробелов.

Отступы

Для отступа используйте 4 пробела. Не используйте символ табуляции.

Максимальная длина строки

Рекомендуемая длина строки составляет 80 символов, т.е. разработчики должны стремиться держать код как можно ближе к 80-символьной границе, когда это возможно. Однако более длинные строки также допустимы. Максимальная длина любой строки PHP-кода не должна превышать 120 символов.

 

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

Директории

В случае если директория является физической частью http адреса раздела:
Для названий директории допустимы буквенно-числовые символы, символы нижнего подчеркивания, тире ("-").
Первая буква в названии директории может быть как заглавная так и строчная.
В случае если директория не является физической частью http адреса:
Для названий директории допустимы буквенно-числовые символы. Символы нижнего подчеркивания, тире ("-"), пробелы и точки запрещены.
Первая буква в названии директории всегда заглавная.

Классы

Используется схема именования классов, в соответствии с которой имена классов напрямую указывают на директории, где они находятся.
Имена классов могут содержать только буквенно-числовые символы. Числа допустимы в именах классов, но не приветствуются. Символы нижнего подчеркивания допустимы в местах разделителей пути - имя файла " User/Db/TableData.php" должно указывать на класс с именем "User_Db_TableData".
Если имя класса состоит из более чем одного слова, то первая буква каждого слова должна быть заглавной. Последующие подряд заглавные буквы недопустимы, например, имя класса "List_PDF" - недопустимо, в то время как "List_Pdf" - допустимо.

Интерфейсы

В основном, интерфейсы следуют тем же соглашениям, что и классы, с одним дополнительным правилом: имена интерфейсов должны начинаться с буквы «I», это заглавная буква «i» и после неё не должно быть нижнего подчеркивания. Пример, IPlugin.

Имена файлов

Для имен файлов допустимы буквенно-числовые символы. Символы нижнего подчеркивания, тире ("-"), пробелы и точки запрещены.


***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

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

Имена функций и методов могут содержать буквенно-числовые символы. Символы нижнего подчеркивания разрешены только в функциях. Числа разрешены в именах функций и методов, но не приветствуются.
Имена функций и методов должны всегда начинаться с буквы в нижнем регистре.
Когда имя метода состоит из более чем одного слова, первая буква каждого нового слова должна быть заглавной. Это обычно называется "верблюжьей(camelCase)" нотацией.

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

Переменные и свойства

Имена переменных и свойств могут содержать буквенно-числовые символы. Символы нижнего подчеркивания не разрешены. Числа разрешены в именах переменных и свойств, но не приветствуются.
Как и имена функций, имена переменных и свойств должны начинаться с буквы в нижнем регистре и следовать "верблюжьей" нотации.
Переменные, являющиеся инстансами объектов, начинаются с заглавной буквы.

$userId = 1

$itemsList = array()

$Object = new Obj()

Многословность приветствуется. Имена переменных должны быть настолько говорящими, насколько это практично. Краткие имена переменных, такие как "$i" и "$n" не приветствуются нигде, кроме ...

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

Константы

Константы могут содержать буквенно-числовые символы, символы нижнего подчеркивания. Числа в именах констант разрешены.
Имена констант должны быть в верхнем регистре, слова в имени должны быть разделены нижним подчеркиванием.
Например, EMBED_SUPPRESS_EMBED_EXCEPTION разрешены, а EMBED_SUPPRESSEMBEDEXCEPTION - нет.
Константы должны быть определены как члены классов с использованием ключевого слова "const". Определение констант в глобальной области видимости с помощью "define" допустимо, но не рекомендуется.

Стиль кодирования

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

PHP-код должен всегда обрамляться полными PHP-тегами:
<?php
 ?>
Короткие теги не допустимы. В файлах, содержащих только PHP-код, закрывающий тэг должен быть опущен.

Строки

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

Для обрамления строки должны использоваться “одинарные кавычки” (‘):
$a = 'Example String';

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

Когда строка литералов сама содержит апострофы, разрешается для обрамления строки использовать "двойные кавычки". Это особенно актуально для SQL-запросов:
$sql = "SELECT `id`, `name` from`people` WHERE `name`='Fred' OR `name`='Susan'";
Синтаксис выше является более предпочтительным, чем экранирование апострофов.

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

Подстановка переменных разрешается только с использованием конкатенации строк. Строки должны объединятся с помощью оператора ".". Пробел должен всегда добавляться до и после оператора "." для улучшения читабельности.
Пример правильной подстановки:
$numberString = 'one ' . $otherNumber . ' five';
Не допустимая подстановка:

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

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

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

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

SQL запросы

Названия SQLкоманд пишутся заглавными буквами. Названия таблиц и колонок пишутся строчными буквами и обрамляются обратными апострофами.

$sql = "SELECT `id`, `name` FROM `people` "

        . "WHERE `people`.`name` = 'Susan' "

        . "ORDER BY `people`.`order` ASC ";

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

Массивы

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

Хотя индекс массива может начинаться с любого неотрицательного числа, но не приветствуется и не рекомендуется начинать индексирование не с 0.
Когда определяется индексированный массив с помощью конструкции array, завершающий пробел должен быть добавлен после каждой запятой для улучшения читабельности:
$sampleArray = array(1, 2, 3, 'end', 'udio');

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

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

Когда определяется ассоциативный массив с помощью конструкции array и название ключей и значений короткие, допускается однострочная запись:
$sampleArray = array('firstKey'  => 'firstValue',  'secondKey' => 'secondValue');
В качестве альтернативы, начальный элемент может располагаться на следующей строке.

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

Классы

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

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

/**

* Doc-блок здесь

*/

class SampleClass

{

    // содержимое класса должно быть

    // с отступом в четыре пробела

}

Классы, расширяющие другие классы или реализующие интерфейсы, должны объявлять свои зависимости на той же строке, если возможно.
class SampleClass extends FooAbstract implements IBarInterface
{
}

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

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

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

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

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

Функции внутри классов должны всегда определять свою область видимости с помощью одного из префиксов private, protected или public.
Как и у классов, фигурная скобка всегда пишется на следующей строке под именем функции. Пробелы между именем функции и круглой скобкой для аргументов не допускаются.
Функции в глобальной области видимости крайне не приветствуются.
Это пример допустимого определения функции:
/**
* Doc-блок здесь
*/
class Foo
{
    /**
     * Doc-блок здесь
     */
    public function bar()
    {
        // содержимое класса должно быть
        // с отступом в четыре пробела
    }
}
В случае, если список аргументов превышает максимальную длину строки, можно делать перенос строки.

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

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

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

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

Вызовы функций и методов

Пробелы ставятся с двух сторон от знака "=". Если подобные присвоения результатов функций переменным объединяются в блоки, то для повышения читабельности рекомендуется следующий синтаксис:
<?php
$short              = foo($bar);
$longVariable = foo($baz);
?>
Если класс поддерживает последовательный вызов методов, то для читабельность используется следующая конструкция.:

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

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

If / Else / Elseif

Управляющие структуры, основанные на конструкциях if и elseif, должны иметь один пробел до открывающей круглой скобки условия, и один пробел после закрывающей круглой скобки.
Внутри выражения условия между круглыми скобками операторы должны разделяться пробелами для читабельности. Внутренние скобки приветствуются для улучшения логической группировки больших условий.
Открывающаяся фигурная скобка пишется на той же строке, что и условие. Закрывающаяся фигурная скобка пишется на отдельной строке. Все содержимое между скобками пишется с отступом в четыре пробела.
if ($a != 2) {
    $a = 2;
}
Если условное выражение заставляет строку превысить максимальную длину строки и имеет несколько условий, вы можете разбить его на несколько строк.

***** Часть текста пропущена (http://php-mysql-highload.blogspot.com) *****

 Пример:
$a = ( $b > 1 ) ? ‘больше’ : ‘меньше’;

Использовать сокращенное условие в другом сокращенном условии запрещается.

Switch

Управляющие структуры, написанные с использованием "switch" конструкции, должны иметь один пробел до открывающей круглой скобки условного выражения, и также один пробел после закрывающей круглой скобки.
Все содержимое между фигурными скобками пишется с отступом в четыре пробела. Содержимое каждого "case" выражения должно писаться с отступом в дополнительные четыре пробела.
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}
Иногда полезно писать case выражения, которые передают управление следующему case выражению, опуская break или return. Для того, чтобы отличать такие случаи от ошибок, каждое case выражение, где опущен break или return, должно содержать комментарий, указывающий, что это сделано преднамеренно.

Комментарии

Подходят комментарии в стилях C (/* */) и C++ (//). Использование комментариев в стиле Perl/shell (#) не рекомендуется.

Встроенная документация

Все блоки документации ("doc-блоки") должны быть совместимы с форматом phpDocumentor. Описание формата phpDocumentor вне рамок данного документа. Для дополнительно информации смотрите: http://phpdoc.org/
Все файлы с классами должны содержать doc-блок "уровня файла" и непосредственно перед каждым классом doc-блок "уровня класса". Примеры таких doc-блоков можно увидеть ниже.

Файлы

Каждый файл, содержащий PHP-код должен иметь заголовочный doc-блок в начале файла:
/**
* Краткое описание файла
*
* Длинное описание файла (если есть)
*
* @package    Magic
*/

Тэг @package должен быть, и иметь значение, соответствующее имени компонента, к которому принадлежит класс.

Классы

Каждый класс должен иметь doc-блок, содержащий как минимум следующие phpDocumentor-теги:
/**
* Краткое описание класса
*
* Длинное описание класса (если есть)...
*
* @package    Magic
* @subpackage Wand
*/

Тэг @package должен быть, и иметь значение, соответствующее имени компонента, к которому принадлежит класс.

Функции

Каждая функция, включая методы объектов, должна иметь doc-блок, содержащий как минимум:

●        Описание функции

●        Все аргументы (@param с описанием типа параметра)

●        Все возможные возвращаемые значения (@return с описанием типа параметра)

Если функция/метод может выбрасывать исключение, используйте тег @throws:
@throws exceptionclass [описание]