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 запросов

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Switch

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

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

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

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

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

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

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

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

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

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

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

  • admin

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

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

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

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

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

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

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

  • 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…
    }