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 запросов
Строки – конкатенация
- Строки могут быть сконкатенированы при помощи оператора “.”, при этом должен присутствовать пробел перед и после оператора
- Для более удобного восприятия длинные строки можно разбивать на несколько, при этом оператор конкатенации ставится в начале строки, на уровне знака присваивания:
1 2 3 4 5 |
<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; '>     </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; '>     </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> |
Массивы с цифровыми индексами
- Отрицательные значения не разрешены для использования в качестве индексов
- Могут начинаться с положительного индекса (больше нуля), но такое не одобряется. Лучше использовать 0 для начала индекса массива
- Для массивов, которые определяются при помощи функции array в несколько строк каждая следующая строка должна начинаться на уровне первого заданного значения в массиве
Ассоциативные массивы
- Если ассоциативный массив определяется при помощи функции array, то каждое новое значение должно быть записано с новой строки. Кроме того задаваемые значения должны находиться на одном уровне
1 2 3 4 |
<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; '>                     </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> |
Обявление класса
- Открывающая фигурная скобка ставится на следующей строке после имени класса (“one true brace” форма)
- Код класса должен иметь отступ в 4 пробела, без табуляций (зачем это снова напоминать? 🙂
- В одном файле – только один класс, не больше
- Добавление дополнительного кода в файл класса не рекомендуется. Если же данная ситуация имеет место, то класс и дополнительный код разделяются двумя пустыми строками
Свойства класса
- Именование свойств класса аналогично именованию обычных переменных (см. выше)
- Свойства класса определяются в самом верху тела класса (до методов)
- Объявление свойств класса осуществляется при помощи спецификаторов доступа private, protected или public (старая конструкция var запрещена)
- Доступ к свойствам класса на прямую, указав для них спецификатор public не одобряется. Пользуйтесь методами аксессорами (get/set)
Методы класса
- Именование методов аналогично правилам для функций
- Методы объявляются при помощи спецификаторов доступа private, protected или public
- Открывающая фигурная скобка пишется с новой строки, после имени метода. Между именем функции и открывающей круглой скобкой никаких пробелов
- Функции в глобальной области видимости сильно не одобряются
- Передача по ссылке разрешена только в объявлении функции
- Аргументы, которые передаются в функцию разделяются запятыми с пробелом
Операторы управления – if/else
- Управляющие операторы if/else должны иметь пробел перед открывающей круглой скобкой (условие), а также пробел после закрывающей круглой скобки
- Для условия внутри скобок операторы отделяются пробелами. Использование круглых скобок для группировки множественных условий одобряется
- Открывающая фигурная скобка пишется на строке, где написано условие. Закрывающая фигурная скобка пишется на отдельной строке. Код внутри фигурных скобок имеет отступ в 4 пробела (а они опять о том же 🙂
1 2 3 4 5 6 7 |
<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; '>    </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; '>    </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> |
Switch
- Также как и для if – пробелы вокруг круглых скобок
- Все операторы switch должны иметь default case
1 2 3 4 5 6 7 8 9 10 11 |
<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; '>    </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; '>        </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; '>        </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; '>    </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; '>        </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; '>        </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; '>    </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> |
Внутритекстовая документация – формат документации
- Все блоки документации (“docblocks”) должны быть совместимы с форматом phpDocumentor
- Все файлы с исходным кодом, написанные для Zend Framework, или которые взаимодействуют с фреймворком, должны содержать блок документации уровня файла (“file-level” docblock) в верхней части каждого файла. А также блок документации уровня класса(“class-level” docblock)
Внутритекстовая документация – файлы
- Каждый файл, содержащий PHP код должен иметь блок документации в формате phpDocumentor. Минимальный блок должен содержать следующее:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
/** * Краткое описание для файла * * Длинное описание для файла (если есть)... * * 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 * */ |
Внутритекстовая документация – классы
- Правила как и для файлов. Минимальный набор phpDocumentor тегов: Descriptions, @copyright, @license, @version, @link, @since, @deprecated
Внутритекстовая документация – функции
- Каждая функция и методы объектов должны иметь блок документации. Он должен содержать описание функции, все аргументы и все возможные возвращаемые значения
- Не обязательно использовать “@access” тег
- Для функций и методов, которые могут выбрасывать исключения лучше использовать @throws тег
Pingback: Блог журналиста()