Zend Framework coding standards – пЕши правЕльно :)

Одной из частей Zend Framework Certification является Zend Coding Standards. Рассмотрим, что нужно знать для успешной сдачи сертификации (материал из официального руководства по подготовке к сертификации).

Хорошие стандарты кодирования являются очень важным аспектом в разработке любого проекта.
Особенно, если над одним проектом трудятся несколько разработчиков.
Наличие стандартов кодирования помогает удостовериться, что код имеет высокое качество,
мало багов и его легко поддерживать.

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

Никогда не используйте закрывающий тег “?>” для файлов, которые содержат только PHP код –
это предотвращает от лишних пробелов и спецсимволов при выводе
Отступ должен – 4 пробела, не используйте символ табуляции
Максимальная длина строки – 120 символов, но старайтесь не превышать количества
в 80 символов для понятности
Строки должны заканчиваться символом перехода на новую строку (Unix), но не символом возврата каретки или комбинацей последнего с первым

Правила именования

Имена классов

Имя класса должно быть привязано к его расположению в директориях (фактически имя класса – путь к файлу класса)
Содержат только буквенно-цифровые символы. Цифры не одобряются. Знак нижнего подчеркивания используется только в качестве разделителя пути к файлу класса (например: Zend/Db/Table.php привязан к Zend_Db_Table)
Имена, содержащие несколько слов: в общем случае, каждое слово содержит большую первую букву, остальные – в нижнем регистре (например: Zend_Pdf). Но есть исключения, когда слово представляет собой сокращение или какое-либо нестандартное слово (например: Zend_XmlRpc)
Классы, созданные разработчиками ZF или его партнерами, должны начинаться на “Zend_” и обязаны быть расположены в иерархии папки Zend/ и с другой стороны класс, написанный не разработчиками ZF никогда не может начинаться на “Zend_”

Интерфейсы

Интерфейсы должны следовать таким же правилам, как и классы, и заканчиваться словом “Interface”
(например: Zend_Log_Adapter_Interface)

Имена файлов

Для всех файлов разрешаются буквенно-цифровые символы, символ подчеркивания и дефис. Пробелы запрещены
Любой файл, который содержит любой PHP код, должен иметь расширение “.php”, за исключением View скриптов

Имена функций

Могут содержать только буквенно-цифровые символы. Символ подчеркивания не разрешается.
Цифры не желательны
Имена, состоящие из нескольких слов: camelCase стиль
Функция должна иметь осмысленное имя для улучшения понимания кода (ну это и так понятно 🙂
Аксессоры для объектов должны начинаться с “get” или “set” (ООП)
(Примечание: не рекомендуется использование функций в глобальной области видимости. В таком случае сделайте эти функции методами статического класса)

Имена методов

Всегда начинаются с буквы в нижнем регистре
Должны содержать имя паттерна, если он применяется
private и protected методы должны начинаться с символа нижнего подчеркивания
(единственный случай, когда символ подчеркивания разрешен в имени метода) – хотя, сами Zendовцы не всегда придерживаются данного пункта 🙂

Имена переменных

Также как и функции могут содержать только буквенно-цифровые символы. Символ подчеркивания не разрешается. Цифры не желательны
Всегда начинаются с буквы в нижнем регистре, camelCase
private и protected переменные начинаются с подчеркивания

Именование констант

Могут содержать буквенно-цифровые символы и знаки подчеркивания
Используются буквы в верхнем регистре
Имена, состоящие из нескольких слов: каждое слово отделяется символом подчеркивания
Должны быть определены как члены класса при помощи конструкции “const”

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

Установка границ PHP кода

PHP код должен быть разграничен тегами <?php и ?>
Короткая запись тегов не разрешена (<? и ?>)

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

Если строка является литералом (не содержит никаких подстановок переменных), то она определяется в одиночных кавычках (например: $str = ‘Пример строки-литерала’)
В случае, если строка содержит апостроф, она может быть заключена в двойные кавычки. Это особенно одобряется для написания SQL запросов

Строки – конкатенация

Строки могут быть сконкатенированы при помощи оператора “.”, при этом должен присутствовать пробел перед и после оператора
Для более удобного восприятия длинные строки можно разбивать на несколько, при этом оператор конкатенации ставится в начале строки, на уровне знака присваивания:

<span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>$sql</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>=</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#2a00ff; background:#ffffe8; '>"SELECT `id`, `name` FROM `people` "</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#000000; background:#ffffe8; '>.</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#2a00ff; background:#ffffe8; '>"WHERE `name` = 'Inga' "</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#000000; background:#ffffe8; '>.</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#2a00ff; background:#ffffe8; '>"ORDER BY `name` ASC"</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
</span>

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

. "WHERE `name` = 'Inga' "

. "ORDER BY `name` ASC";

Массивы с цифровыми индексами

Отрицательные значения не разрешены для использования в качестве индексов
Могут начинаться с положительного индекса (больше нуля), но такое не одобряется. Лучше использовать 0 для начала индекса массива
Для массивов, которые определяются при помощи функции array в несколько строк каждая следующая строка должна начинаться на уровне первого заданного значения в массиве

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

Если ассоциативный массив определяется при помощи функции array, то каждое новое значение должно быть записано с новой строки. Кроме того задаваемые значения должны находиться на одном уровне

<span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>$sampleArray</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>=</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>array</span><span style='color:#000000; background:#ffffe8; '>(</span><span style='color:#2a00ff; background:#ffffe8; '>'firstKey'</span><span style='color:#000000; background:#ffffe8; '>  </span><span style='color:#000000; background:#ffffe8; '>=</span><span style='color:#000000; background:#ffffe8; '>></span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#2a00ff; background:#ffffe8; '>'firstValue'</span><span style='color:#000000; background:#ffffe8; '>,</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#2a00ff; background:#ffffe8; '>'secondKey'</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>=</span><span style='color:#000000; background:#ffffe8; '>></span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#2a00ff; background:#ffffe8; '>'secondValue'</span><span style='color:#000000; background:#ffffe8; '>)</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
</span>

$sampleArray = array('firstKey' => 'firstValue',

'secondKey' => 'secondValue');

Обявление класса

Открывающая фигурная скобка ставится на следующей строке после имени класса (“one true brace” форма)
Код класса должен иметь отступ в 4 пробела, без табуляций (зачем это снова напоминать? 🙂
В одном файле – только один класс, не больше
Добавление дополнительного кода в файл класса не рекомендуется. Если же данная ситуация имеет место, то класс и дополнительный код разделяются двумя пустыми строками

Свойства класса

Именование свойств класса аналогично именованию обычных переменных (см. выше)
Свойства класса определяются в самом верху тела класса (до методов)
Объявление свойств класса осуществляется при помощи спецификаторов доступа private, protected или public (старая конструкция var запрещена)
Доступ к свойствам класса на прямую, указав для них спецификатор public не одобряется. Пользуйтесь методами аксессорами (get/set)

Методы класса

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

Операторы управления – if/else

Управляющие операторы if/else должны иметь пробел перед открывающей круглой скобкой (условие), а также пробел после закрывающей круглой скобки
Для условия внутри скобок операторы отделяются пробелами. Использование круглых скобок для группировки множественных условий одобряется
Открывающая фигурная скобка пишется на строке, где написано условие. Закрывающая фигурная скобка пишется на отдельной строке. Код внутри фигурных скобок имеет отступ в 4 пробела (а они опять о том же 🙂

<span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>if</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>(</span><span style='color:#000000; background:#ffffe8; '>$someValue</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>></span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>0</span><span style='color:#000000; background:#ffffe8; '>)</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>{</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#000000; background:#ffffe8; '>$checked</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>=</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>true</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>}</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>else</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>{</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#000000; background:#ffffe8; '>$newValue</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>=</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>7</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>}</span><span style='color:#000000; background:#ffffe8; '></span>
</span>

if ($someValue > 0) {

$checked = true;

} else {

$newValue = 7;

}

Switch

Также как и для if – пробелы вокруг круглых скобок
Все операторы switch должны иметь default case

<span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>switch</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>(</span><span style='color:#000000; background:#ffffe8; '>$key</span><span style='color:#000000; background:#ffffe8; '>)</span><span style='color:#000000; background:#ffffe8; '> </span><span style='color:#000000; background:#ffffe8; '>{</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>case</span><span style='color:#000000; background:#ffffe8; '> KEY_UP</span><span style='color:#000000; background:#ffffe8; '>:</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#000000; background:#ffffe8; '>$obj</span><span style='color:#000000; background:#ffffe8; '>-</span><span style='color:#000000; background:#ffffe8; '>></span><span style='color:#000000; background:#ffffe8; '>moveUp</span><span style='color:#000000; background:#ffffe8; '>(</span><span style='color:#000000; background:#ffffe8; '>)</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>break</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>case</span><span style='color:#000000; background:#ffffe8; '> KEY_DOWN</span><span style='color:#000000; background:#ffffe8; '>:</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#000000; background:#ffffe8; '>$obj</span><span style='color:#000000; background:#ffffe8; '>-</span><span style='color:#000000; background:#ffffe8; '>></span><span style='color:#000000; background:#ffffe8; '>moveDown</span><span style='color:#000000; background:#ffffe8; '>(</span><span style='color:#000000; background:#ffffe8; '>)</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>break</span><span style='color:#000000; background:#ffffe8; '>;</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>&#xa0;&#xa0;&#xa0;&#xa0;</span><span style='color:#7f0055; background:#ffffe8; font-weight:bold; '>default</span><span style='color:#000000; background:#ffffe8; '>:</span><span style='color:#000000; background:#ffffe8; '></span>
<span style='color:#000000; background:#ffffe8; '>}</span><span style='color:#000000; background:#ffffe8; '></span>
</span>

switch ($key) {

case KEY_UP:

$obj->moveUp();

break;

case KEY_DOWN:

$obj->moveDown();

default:

}

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

Все блоки документации (“docblocks”) должны быть совместимы с форматом phpDocumentor
Все файлы с исходным кодом, написанные для Zend Framework, или которые взаимодействуют с фреймворком, должны содержать блок документации уровня файла (“file-level” docblock) в верхней части каждого файла. А также блок документации уровня класса(“class-level” docblock)

Внутритекстовая документация – файлы

Каждый файл, содержащий PHP код должен иметь блок документации в формате phpDocumentor. Минимальный блок должен содержать следующее:

/**
 * Краткое описание для файла
 *
 * Длинное описание для файла (если есть)...
 *
 * LICENSE: информация о лицензии
 *
 * @copyright 2009 Zend Technologies
 * @license    http://www.zend.com/license/3_0.txt    PHP License 3.0
 * @version    $Id:$
 * @link         http://dev.zend.com/package/PackageName
 * @since      File available since Release 1.2.0
 *
 */

/**

* Краткое описание для файла

* Длинное описание для файла (если есть)...

* LICENSE: информация о лицензии

* @license http://www.zend.com/license/3_0.txt PHP License 3.0

* @version $Id:$

* @link http://dev.zend.com/package/PackageName

* @since File available since Release 1.2.0

Внутритекстовая документация – классы

Правила как и для файлов. Минимальный набор phpDocumentor тегов: Descriptions, @copyright, @license, @version, @link, @since, @deprecated

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

Каждая функция и методы объектов должны иметь блок документации. Он должен содержать описание функции, все аргументы и все возможные возвращаемые значения
Не обязательно использовать “@access” тег
Для функций и методов, которые могут выбрасывать исключения лучше использовать @throws тег

[YS.PRO]

У Зенда свои стандарты, это ладно. Вот не соглашусь насчет того, что наличие стандартов кодирования помогает удостовериться, что код имеет высокое качество,
мало багов.
Можно красиво писать “кривое” приложение с лесом багов )))
CharnaD

Не могу отказаться от ‘?>’
Хоть убейте, но я его буду ставить.
[YS.PRO]

А я довольно легко отказался, как раз после того, как почитал об этом. Другое дело, что во многих IDE “?>” автоматом генерится.
admin

IDE можно просто настроить, чтоб она автоматом не ставила закрывающий php тег
adw0rd

>Отступ должен – 4 пробела, не
>используйте символ табуляции

Чем пробелы лучше? Как по мне так потом запарка их удалять… Чем табы не угодили?
Needge

@adw0rd:
использование пробелов позволяет соблюдать форматирование кода в разных редакторах (потому что не все редакторы поддерживают символы табуляции)
Phil

По-моему, это надуманная проблема. Все более-менее приличные редакторы отлично поддерживают табы. К тому же, это дело привычки.
Alex Snet

Не, на мой взгляд полезная дока.
Но всетаки. Уже какой раз повторяюсь – “Стиль кодирования” не есть “Правила написания кода”, если не брать контекст.
Всетаки стиль кодирования это то, как и каким алгоритмом что-либо кодировать.
Это такая маленькая, но очень бросающаяся в глаза, на мой взгляд помарка.
Она же и на офф. сайте зенда есть.
Евгений

Очень грамотный и полный пост. Одно огорчает – не все правила стилистики использую, хотя придет время, я всеже начну писать по всем правилам кодирования Zend 😉
dypa

и почему они не юзают венгрскую нотацию (http://ru.wikipedia.org/wiki/%D0%92%D0%B5%D0%BD%D0%B3%D0%B5%D1%80%D1%81%D0%BA%D0%B0%D1%8F_%D0%BD%D0%BE%D1%82%D0%B0%D1%86%D0%B8%D1%8F) ?
Pingback: Блог журналиста()
lcf

Использование пробелов хорошо еще и тем, что можно выравнивать код очень красиво и читабельно не только там где отступы в итерациях, условиях и прочих вложенных блоках, но и в других местах. (например – см. конкатенацию строк)
Можно конечно смешивать табы и пробелы, но мешанины будет меньше если будут использовать только пробелы.
lcf

У вас где-то потерялись картинки смайлов.
admin

А где именно?
lcf

Везде

http://floomby.ru/content/G63LWGhDpU/

Он пытается показать там вот эту картинку: http://snowcore.net/wp-includes/images/smilies/icon_wink.gif
admin

У вас наверное Safari ?
lcf

Нет у меня опера. Дело не в этом, gif картинки любой браузер может показывать, даже ИЕ 🙂 :
http://floomby.ru/content/PG3WhGEBFE/

Попробуйте перейти по ссылке в любом браузере, просто файла с картинкой либо нет либо реврайт неправильно настроен я не знаю:
http://snowcore.net/wp-includes/images/smilies/icon_wink.gif
admin

Самое интересное, что папки smilies у меня вообще нет 🙂
Спасибо за замечание, будет время – подправим.
Kama

And I have my own standart,which I cannot eliminate from my style, it`s

function test($…)
{
//code…
}

Magento Developer's Blog