Этот документ предоставляет указания и ресурсы для разрабочиков и команд работающих на Zend Framework’ом. Освещаемые здесь темы: Форматирование PHP-файлов Соглашения по именованию Стиль кодирования Встроенная документация Хороший стандарт кодирования важен в любом проекте, и особенно там, где множество разработчиков работают над одним проектом. Наличие стандарта кодирования помогает гарантировать, что код высокого качества, с меньшим количеством ошибок, и легко поддерживается. Для файлов, содержащих только PHP-код, закрывающийся тег ("?>") не разрешен. Он не требуется синтаксисом PHP. Это предотвращает от случайного включения в вывод конечных пробелов. ВАЖНО: Включение бинарных файлов как разрешает __HALT_COMPILER() запрещено из любого PHP-файла Zend framework'а или файлов производных от него. Эта возможность разрешена для использования только в специальных инсталляционных скриптах. Для отступа используйте 4 пробела. Не используйте символ табуляции. Рекомендуемая длина строки составляет 80 символов, т.е. разработчики должны стремиться держать код как можно ближе к 80-символьной границе, когда это возможно. Однако более длинные строки также допустимы. Максимальная длина любой строки PHP-кода не должна превышать 120 символов. Переводы строк должны быть как принято для текстовых файлов в Unix-системах. Строки должны заканчиваться только символом перевода на новую строку (LF). Символ перевода на новую строку в десятичном виде представляется как число 10, или как 0x0A в шестнадцатеричном. Не используйте комбинацию символов возврата каретки/перевода строки (CRLF) как на Windows-компьютерах (0x0D, 0x0A). Zend Framework использует схему именования классов, в соответсвтвии с которой имена классов напрямую указывают на директории, где они находятся. Корневой директорией Zend Framework'а является директория "Zend/", в которой иерархически расположены все классы. Имена классов могут содержать только буквенно-числовые символы. Числа допустимы в именах классов, но не приветствуются. Символы нижнего подчеркивания допустимы в местах разделителей пути - имя файла "Zend/Db/Table.php" должно указывать на класс с именем "Zend_Db_Table". Если имя класса состоит из более чем одного слова, то первая буква каждого слова должна быть заглавной. Последующие заглавные буквы недопустимы, например, имя класса "Zend_PDF" - недопустимо, в то время как имя "Zend_Pdf" допустимо. Классы Zend Framework'а написанных Zend'ом или одной из участвующих компаний-партнеров и распространяемых с фреймворком должны всегда начинаться с префикса "Zend_" и должны располагаться в директории "Zend/" в соответствии с иерархией. Ниже примеры допустимых имен классов: ВАЖНО: Код, который оперирует с фреймворком, но не является его частью, например, код написанный пользователем фреймворка и это не компания Zend или один из партнеров по фреймворку, не должен начинаться с префикса "Zend_". Интерфейсы должны следовать той же схеме именования, как и классы (смотрите выше), однако должны заканчиваться словом "Interface", как в следующих примерах: Для файлов допустимы буквенно-числовые символы, символы нижнего подчеркивания и тире ("-"). Пробелы запрещены. Любой файл содержащий PHP-код должен иметь расширение ".php". Это примеры показывают допустимые имена файлов для классов из примеров в секции выше: Имена файлов отражаются на имена классов, как описано выше. Имена функций могут содержать буквенно-числовые символы. Символы нижнего подчеркивания не разрешены. Числа разрешены в именах функций, но не приветствуются. Имена функций должны всегда начинатся с буквы в нижнем регистре. Когда имя функции состоит из более чем одного слова, первая буква каждого нового слова должна быть заглавной. Это обычно называется "верблюжьей" нотацией. Многословность приветствуется. Имена функций должны быть настолько говорящими, насколько это практично для повышения понимаемости кода. Это примеры допустимых имен функций: Для объектно-ориентированного программирования принято, чтобы методы доступа имели префикс "get" или "set". Когда используются шаблоны проектирования, такие, как "синглтон" или "фабрика", имена методов должны содержать имя шаблона, чтобы можно было быстро узнать шаблон. Функции в глобальной области видимости ("плавающие функции") допустимы, но не приветствуются. Рекомендуется обрамлять такие функции в статические классы. Имена переменных могут содержать буквенно-числовые символы. Символы нижнего подчеркивания не разрешены. Числа разрешены в именах переменных, но не приветствуются. Для переменных - членов классов, определенных с помощью префиксов области видимости "private" или "protected", первый символ имени должен быть один символ нижнего подчеркивания. Это единственное допустимое использование символа нижнего подчеркивания в имени. Переменные - члены классов определенные с помощью префикса области видимости "public" никогда не должны начинаться с символа нижнего подчеркивания. Как и имена функций (смотрите секцию 3.3 выше) имена переменных должны начинаться с буквы в нижнем регистре и следовать "верблюжьей" нотации. Многословность приветствуется. Имена переменных должны быть настолько говорящими, насколько это практично. Краткие имена переменных, такие как "$i" и "$n" не приветствуются нигде, кроме как в контексте маленьких циклов. Если цикл содержит более 20 строк кода, то переменные для индексов должны иметь более говорящие имена. Константы могут содержать буквенно-числовые символы и символы нижнего подчеркивания. Числа разрешены в именах констант. Имена констант должны быть в верхнем регистре. Константы должны быть определены как члены классов с использованием ключевого слова "const". Определение констант в глобальной области видимости с помощью "define" допустимо, но не рекомендуется. PHP-код должен всегда обрамлятся полными PHP-тегами: ]]> Короткие теги не допустимы. Когда строка является литеральной (не содержит подстановок переменных), для ее обрамления должны использоваться апострофы или "одинарные кавычки": Когда строка литералов сама содержит апострофы, разрешается для обрамления строки использовать "двойные кавычки". Это особенно актуально для SQL-запросов: Синтаксис выше является более предпочтительным, чем экранирование апострофов. Подстановка переменных разрешается с использованием двух нижеприведенных форм: Для надежности, эта форма не допустима: Строки должны объединятся с помощью оператора ".". Пробел должен всегда добавлятся до и после оператора "." для улучшения читабельности: Когда производится конкатенация строк с помощью оператора ".", разрешается разрывать выражение на несколько строк для улучшения читабельности. В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы оператор "." был выровнен под оператором "=": Отрицательные числа в качестве индексов запрещены. Хотя индекс массива может начинаться с отрицательного числа, но это не приветствуется и рекомендуется, чтобы все массивы начинали индексирование с 0. Когда определяется индексированный массив с помощью конструкции array, завершающий пробел должен быть добавлен после каждой запятой для улучшения читабельности: Также разрешается определять многострочные индексированные массивы, используя конструкцию "array". В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы начало каждой строки было выравнено как показано ниже: Когда определяется ассоциативный массив с помощью конструкции "array", приветствуется разделение выражения на несколько строк. В этом случае, каждая следующая строка должна быть дополнена с помощью пробелов так, чтобы и ключи и значения были выровнены: 'firstValue', 'secondKey' => 'secondValue');]]> Классы должны определяться по следующей схеме. Фигурная скобка всегда пишется на следующей строке под именем класса. Каждый класс должен иметь блок документации (doc-блок) в соответствии со стандартом PHPDocumentor. Код внутри класса должен иметь отступ в четыре пробела. Только один класс разрешен внутри одного PHP-файла. Размещение дополнительно кода в файле с классом разрешено, но не приветствуется. В таких файлах, две пустые строки должны разделять класс и дополнительный PHP-код. Это пример допустимого определения класса: Переменные-члены классов должны определяться по следующей схеме. Любые переменные, определенные в классе, должны быть определены в начале класса, до определения любого метода. Ключевое слово var не разрешено. Члены класса должны всегда определять их область видимости, используя ключевое слово private, protected или public. Доступ к переменным-членам класса напрямую используя префикс public разрешено, но не приветствуется в пользу методов доступа (set/get). Функции должны определяться по следующей схеме. Функции внутри классов должны всегда определять свою область видимости с помощью одного из префиксов private, protected или public. Как и у классов, фигурная скобка всегда пишется на следующей строке под именем функции. Пробелы между именем функции и круглой скобкой для аргументов отсутствуют. Функции в глобальной области видимости крайне не приветствуются. Это пример допустимого определения функции: ЗАМЕЧАНИЕ: Передача по ссылке допустима только в определениях функций: Передача по ссылке во время вызова запрещена. Возвращаемое значение не должно обрамляться в круглые скобки, иначе это ухудшает читабельность, а также может поломать код, если метод позже станет возвращать результат по ссылке. bar); } /** * ХОРОШО */ public function bar() { return $this->bar; } }]]> Аргументы функции разделяются одним завершающим пробелом после каждой запятой. Это пример допустимого вызова функции для функции, которая принимает три аргумента: Передача по ссылке во время вызова запрещена. Смотрите секцию определения функций для правильного способа передачи аргументов функции по ссылке. Для функций, чьи аргументы допускают массив, вызов функции может включать конструкцию "array" и может быть разделено на несколько строк для улучшения читабельности. В этом случае, применим стандарт описания массивов: Управляющие структуры, основанные на конструкциях if и elseif, должны иметь один пробел до открывающей круглой скобки условия, и один пробел после закрывающей круглой скобки. Внутри выражения условия между круглыми скобками операторы должны разделяться пробелами для читабельности. Внутренние скобки приветствуются для улучшения логической группировки больших условий. Открывающаяся фигурная скобка пишется на той же строке, что и условие. Закрывающаяся фигурная скобка пишется на отдельной строке. Все содержимое между скобками пишется с отступом в четыре пробела. Для выражения "if", включая "elseif" или "else", форматирование должно быть таким, как в следующем примере: PHP допускает написание таких выражений без фигурных скобок при некоторых условиях. Стандарт кодирования не делает различий - для всех "if", "elseif" или "else" выражений необходимо использовать фигурные скобки. Использование "elseif" конструкции допускается, но крайне не приветствуется в пользу "else if" комбинации. Управляющие структуры написанные с использованием "switch" конструкции должны иметь один пробел до открывающей круглой скобки условного выражения, и также один пробел после закрывающей круглой скобки. Все содержимое между фигурными скобками пишется с отступом в четыре пробела. Содержимое каждого "case" выражения должно писаться с отступом в дополнительные четыре пробела. Ключевое слово default никогда не должно опускаться в выражении switch. ЗАМЕЧАНИЕ: Иногда полезно писать case выражения, которые передают управление следующему case выражению, опуская break или return. Для того, чтобы отличать такие случаи от ошибок, каждое case выражение, где опущен break или return, должно содержать комментарий "// break intentionally omitted". Все блоки документации ("doc-блоки") должны быть совместимы с форматом phpDocumentor. Описание формата phpDocumentor вне рамок данного докумета. Для дополнительно информации смотрите: http://phpdoc.org/ Все файлы с исходными кодами, написанные для Zend Framework'а, или которые оперируют с фреймворком, должны содержать "файловые" doc-блоки в начале каждого файла и "классовый" doc-блок непосредственно перед каждым классом. Ниже даны примеры таких doc-блоков. Каждый файл, содержащий PHP-код должен иметь заголовочный блок в начале файла, содержащий как минимум следующие phpDocumentor-теги: Каждый класс должен иметь doc-блок, содержащий как минимум следующие phpDocumentor-теги: Каждая функция, включая методы объектов, должна иметь doc-блок, содержащий как минимум: Описание функции Все аргументы Все возможные возвращаемые значения Нет надобности использовать тег "@access", потому что область видимости уже известна из ключевых слов "public", "private" или "protected". используемых при определении функции. Если функция/метод может выбрасывать исключение, используйте тег @throws: