repo_zf1/documentation/manual/ru/ref/coding_standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<appendix id="coding-standard">
  <title>Стандарт кодирования на PHP в Zend Framework'е</title>
    <sect1 id="coding-standard.overview">
        <title>Обзор</title>

        <sect2 id="coding-standard.overview.scope">
            <title>Область применения</title>

            <para>
                Этот документ предоставляет указания по форматированию кода и документированию для
                разработчиков и команд, работающих с Zend Framework'ом. Многие разработчики,
                использующие Zend Framework, также находят эти указания полезными, так как стиль
                их кода остается единообразным со всем кодом Zend Framework. Так же, стоит заметить,
                что требуются значительные усилия для полного определения стандартов кодирования.
            </para>

            <note>
                <para>
                    Иногда разработчики считают само введение стандарта более важным, нежели то, что
                    именно конкретный стандарт предполагает на более детальном уровне. В Стандарте
                    кодирования Zend Framework'а описываются приемы и практики, которые хорошо
                    зарекомендовали себя для проекта Zend Framework. Вы можете модифицировать этот
                    стандарт или использовать как есть, в соответствии с условиями нашей <ulink
                        url="http://framework.zend.com/license">лицензии</ulink>.
                </para>
            </note>

            <para>
                Освещаемые темы в Стандарте кодирования Zend Framework'а включают:
            </para>

            <itemizedlist>
                <listitem>
                    <para>Форматирование <acronym>PHP</acronym>-файлов</para>
                </listitem>

                <listitem>
                    <para>Соглашения по именованию</para>
                </listitem>

                <listitem>
                    <para>Стиль кодирования</para>
                </listitem>

                <listitem>
                    <para>Встроенная документация</para>
                </listitem>
            </itemizedlist>
        </sect2>

        <sect2 id="coding-standard.overview.goals">
            <title>Цели</title>

            <para>
                Хороший стандарт кодирования важен в любом проекте, и особенно там,
                где множество разработчиков работают над одним проектом. Наличие
                стандарта кодирования помогает гарантировать, что код - высокого
                качества, с меньшим количеством ошибок и легко поддерживается.
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.php-file-formatting">
        <title>Форматирование PHP-файлов</title>

        <sect2 id="coding-standard.php-file-formatting.general">
            <title>Общее</title>

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

            <note>
                <para>
                    <emphasis>ВАЖНО:</emphasis> Включение бинарных файлов, как разрешает
                    <methodname>__HALT_COMPILER()</methodname>, запрещено из любого
                    <acronym>PHP</acronym>-файла Zend Framework'а или файлов производных от него.
                    Эта возможность разрешена для использования только в специальных инсталляционных
                    скриптах.
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.indentation">
            <title>Отступы</title>

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

        <sect2 id="coding-standard.php-file-formatting.max-line-length">
            <title>Максимальная длина строки</title>

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

        <sect2 id="coding-standard.php-file-formatting.line-termination">
            <title>Переводы строк</title>

            <para>
                Переводы строк должны быть как принято для текстовых файлов в
                Unix-системах. Строки должны заканчиваться только символом
                перевода на новую строку (LF). Символ перевода на новую строку
                в десятичном виде представляется как число 10, или как 0x0A в
                шестнадцатеричном.
            </para>

            <para>
                Не используйте комбинацию символов возврата каретки/перевода
                строки (<acronym>CRLF</acronym>) как на Windows-компьютерах (0x0D, 0x0A).
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.naming-conventions">
        <title>Соглашения по именованию</title>

        <sect2 id="coding-standard.naming-conventions.classes">
            <title>Классы</title>

            <para>
                Zend Framework использует схему именования классов, в соответствии с которой имена
                классов напрямую указывают на директории, где они находятся. Корневой директорией
                стандартной библиотеки Zend Framework'а является директория "Zend/", а
                дополнительной - директория "ZendX/". Все классы Zend Framework расположены
                иерархически в этих корневых директориях.
            </para>

            <para>
                Имена классов могут содержать только буквенно-числовые символы.
                Числа допустимы в именах классов, но не приветствуются.
                Символы нижнего подчеркивания допустимы в местах разделителей
                пути - имя файла "<filename>Zend/Db/Table.php</filename>" должно указывать на класс
                с именем "<classname>Zend_Db_Table</classname>".
            </para>

            <para>
                Если имя класса состоит из более чем одного слова, то первая буква каждого слова
                должна быть заглавной. Последующие заглавные буквы недопустимы, например, имя класса
                "Zend_PDF" - недопустимо, в то время как "<classname>Zend_Pdf</classname>" -
                допустимо.
            </para>

            <para>
                Эти соглашения определяют механизм псевдо-нэймспэйсов для Zend Framework.
                Zend Framework будет использовать функционал <acronym>PHP</acronym> нэймспэйсов,
                когда он станет доступен и применим для разработчиков для использования в их
                приложениях.
            </para>

            <para>
                Смотри имена классов в стандартной и дополнительной библиотеках в качестве примера
                этой схемы именования.
            </para>

            <note>
                <para>
                    <emphasis>ВАЖНО</emphasis>: Код, который должен использоваться вместе с
                    Zend Framework, но не являющийся частью стандартной либо дополнительной
                    библиотек (тоесть код приложения или библиотеки, распространяемый не компанией
                    Zend), не должен начинаться с префиксов "Zend_" или "ZendX_" .
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.abstracts">
            <title>Абстрактные классы</title>

            <para>
                В основном, абстрактные классы следуют тем же соглашениям, что и <link
                    linkend="coding-standard.naming-conventions.classes">классы</link>, с одним
                дополнительным правилом: имена абстрактных классов должны заканчиваться словом
                "Abstract" и перед ним не должно быть нижнего подчеркивания. Как пример,
                <classname>Zend_Controller_Plugin_Abstract</classname> считается неправильным, в то
                время как <classname>Zend_Controller_PluginAbstract</classname> или
                <classname>Zend_Controller_Plugin_PluginAbstract</classname> - правильны.
            </para>

            <note>
                <para>
                    Эта схема именования появилась с версии 1.9.0 Zend Framework'a. Классы,
                    предшествующие этой версии могут не следовать данному правилу, но в будущем
                    будут переименованы для соответствия.
                </para>

                <para>
                    Логическое обоснование этому изменению связано с использованием нэймспэйсов.
                    Планируя переход к Zend Framework 2.0 и использование <acronym>PHP</acronym>
                    5.3, мы готовимся использовать нэймспэйсы. Простейший способ автоматизировать
                    переход к нэймспэйсам - это просто преобразовать нижнее подчеркивание в
                    разделитель нэймспэйса, но в случае старой схемы именования это сделает
                    итоговым именем классов просто "Abstract" или "Interface", которые являются
                    зарезервированными ключевыми словами в <acronym>PHP</acronym>. Если же мы
                    добавим имя (суб)компонента к имени класса, то сможем избежать этих проблем.
                </para>

                <para>
                    Для демонстрации ситуации, представьте преобразование класса
                    <classname>Zend_Controller_Request_Abstract</classname> для использования
                    нэймспэйсов:
                </para>

                <programlisting language="php"><![CDATA[
namespace Zend\Controller\Request;

abstract class Abstract
{
    // ...
}
]]></programlisting>

                <para>
                    Очевидно, это не сработает. Но с новой схемой именования это будет
                    выглядеть так:
                </para>

                <programlisting language="php"><![CDATA[
namespace Zend\Controller\Request;

abstract class RequestAbstract
{
    // ...
}
]]></programlisting>

                <para>
                    Мы сохраняем семантику и разделением нэймспэйсами, в тоже время мы избегаем
                    проблем с ключевыми словами. Так же, так лучше описывается абстрактный класс.
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.interfaces">
            <title>Интерфейсы</title>

            <para>
                В основном, интерфейсы следуют тем же соглашениям, что и <link
                    linkend="coding-standard.naming-conventions.classes">классы</link>, с одним
                дополнительным правилом: имена интерфейсов должны заканчиваться словом
                "Interface" и перед ним не должно быть нижнего подчеркивания. Как пример,
                <classname>Zend_Controller_Plugin_Interface</classname> считается неправильным, в то
                время как <classname>Zend_Controller_PluginInterface</classname> или
                <classname>Zend_Controller_Plugin_PluginInterface</classname> - правильны.
            </para>

            <para>
                Хотя это правило не считается обязательным, оно настоятельно рекомендуется, так как
                предоставляет разработчикам хороший визуальный ключ к пониманию, какие файлы
                содержат интерфейсы, а не классы.
            </para>

            <note>
                <para>
                    Эта схема именования появилась с версии 1.9.0 Zend Framework'a. Интерфейсы,
                    предшествующие этой версии могут не следовать данному правилу, но в будущем
                    будут переименованы для соответствия. Смотри <link
                        linkend="coding-standard.naming-conventions.abstracts">предыдущую секцию
                    </link> для дополнительной информации по логическому обоснованию этого изменения
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.filenames">
            <title>Имена файлов</title>

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

            <para>
                Любой файл содержащий <acronym>PHP</acronym>-код должен иметь расширение
                "<filename>.php</filename>", за исключением скриптов вида.
                Это примеры показывают допустимые имена файлов для классов из
                примеров в секции выше:
            </para>

                <programlisting language="php"><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php
]]></programlisting>

            <para>
                Имена файлов отражаются на имена классов, как описано выше.
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.functions-and-methods">
            <title>Функции и методы</title>

            <para>
                Имена функций могут содержать буквенно-числовые символы.
                Символы нижнего подчеркивания не разрешены. Числа разрешены в
                именах функций, но не приветствуются.
            </para>

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

            <para>
                Многословность приветствуется. Имена функций должны быть
                настолько говорящими, насколько это практично для повышения
                понимаемости кода.
            </para>

            <para>
                Это примеры допустимых имен функций:
            </para>

            <programlisting language="php"><![CDATA[
filterInput()

getElementById()

widgetFactory()
]]></programlisting>

            <para>
                Для объектно-ориентированного программирования принято, чтобы
                методы доступа имели префикс "get" или "set".
                Когда используются шаблоны проектирования, такие, как "синглтон"
                или "фабрика", где возможно, имена методов должны содержать имя шаблона, чтобы
                можно было быстро узнать шаблон.
            </para>

            <para>
                Для методов, объявленных с помощью префиксов области видимости "private" или
                "protected", первый символ имени должен быть нижним подчеркиванием. Это единственное
                допустимое применение нижнего подчеркивания в имени метода. Методы объявленные как
                "public" никогда не должны иметь нижнего подчеркивания в имени.
            </para>

            <para>
                Функции в глобальной области видимости ("плавающие функции")
                допустимы, но не приветствуются. Рекомендуется обрамлять такие
                функции в статические классы.
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.variables">
            <title>Переменные</title>

            <para>
                Имена переменных могут содержать буквенно-числовые символы.
                Символы нижнего подчеркивания не разрешены. Числа разрешены в
                именах переменных, но не приветствуются.
            </para>

            <para>
                Для переменных - членов классов, определенных с помощью
                префиксов области видимости "private" или "protected", первый
                символ имени должен быть символом нижнего подчеркивания. Это
                единственное допустимое использование символа нижнего
                подчеркивания в имени. Переменные - члены классов определенные
                с помощью префикса области видимости "public" никогда не должны
                начинаться с символа нижнего подчеркивания.
            </para>

            <para>
                Как и имена функций (смотри секцию 3.3), имена переменных должны начинаться с буквы
                в нижнем регистре и следовать "верблюжьей" нотации.
            </para>

            <para>
                Многословность приветствуется. Имена переменных должны быть
                настолько говорящими, насколько это практично. Краткие имена
                переменных, такие как "<varname>$i</varname>" и "<varname>$n</varname>" не
                приветствуются нигде, кроме как в контексте маленьких циклов. Если цикл содержит
                более 20 строк кода, то переменные для индексов должны иметь
                более говорящие имена.
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.constants">
            <title>Константы</title>

            <para>
                Константы могут содержать буквенно-числовые символы, символы нижнего подчеркивания.
                Числа в именах констант разрешены.
            </para>

            <para>
                Имена констант должны быть в верхнем регистре, слова в имени должны быть разделены
                нижним подчеркиванием.
            </para>

            <para>
                Например, <constant>EMBED_SUPPRESS_EMBED_EXCEPTION</constant> разрешены, а
                <constant>EMBED_SUPPRESSEMBEDEXCEPTION</constant> - нет.
            </para>

            <para>
                Константы должны быть определены как члены классов с
                использованием ключевого слова "const". Определение констант в
                глобальной области видимости с помощью "define" допустимо, но
                не рекомендуется.
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.coding-style">
        <title>Стиль кодирования</title>

        <sect2 id="coding-standard.coding-style.php-code-demarcation">
            <title>Обрамление PHP-кода</title>

            <para>
                <acronym>PHP</acronym>-код должен всегда обрамляться полными
                <acronym>PHP</acronym>-тегами:
            </para>

            <programlisting language="php"><![CDATA[
<?php

?>
]]></programlisting>

            <para>
                Короткие теги не допустимы. В файлах, содержащих только <acronym>PHP</acronym>-код,
                закрывающий так должен быть опущен. (Смотри <link
                    linkend="coding-standard.php-file-formatting.general">Общие стандарты</link>).
            </para>
        </sect2>

        <sect2 id="coding-standard.coding-style.strings">
            <title>Строки</title>

            <sect3 id="coding-standard.coding-style.strings.literals">
                <title>Строковые литералы</title>

                <para>
                    Когда строка является литеральной (не содержит подстановок
                    переменных), для ее обрамления должны использоваться
                    апострофы или "одинарные кавычки":
                </para>

                <programlisting language="php"><![CDATA[
$a = 'Example String';
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
                <title>Строковые литералы, содержащие апострофы</title>

                <para>
                    Когда строка литералов сама содержит апострофы, разрешается
                    для обрамления строки использовать "двойные кавычки". Это
                    особенно актуально для <constant>SQL</constant>-запросов:
                </para>

                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
]]></programlisting>

                <para>
                    Синтаксис выше является более предпочтительным, чем
                    экранирование апострофов.
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.variable-substitution">
                <title>Подстановка переменных</title>

                <para>
                    Подстановка переменных разрешается с использованием нижеприведенных форм:
                </para>

                <programlisting language="php"><![CDATA[
$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";
]]></programlisting>

                <para>
                    Для надежности, эта форма не допустима:
                </para>

                <programlisting language="php"><![CDATA[
$greeting = "Hello ${name}, welcome back!";
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.string-concatenation">
                <title>Конкатенация строк</title>

                <para>
                    Строки должны объединятся с помощью оператора ".". Пробел
                    должен всегда добавляться до и после оператора "." для
                    улучшения читабельности:
                </para>

                <programlisting language="php"><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';
]]></programlisting>

                <para>
                    Когда производится конкатенация строк с помощью оператора
                    ".", разрешается разрывать выражение на несколько строк для
                    улучшения читабельности. В этом случае, каждая следующая
                    строка должна быть дополнена пробелами так, чтобы оператор
                    "." был выровнен под оператором "=":
                </para>

                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.arrays">
            <title>Массивы</title>

            <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
                <title>Массивы с числовыми индексами</title>

                <para>Отрицательные числа в качестве индексов запрещены.</para>

                <para>
                    Хотя индекс массива может начинаться с любого неотрицательного числа,
                    но не приветствуется и не рекомендуется начинать индексирование не с 0.
                </para>

                <para>
                    Когда определяется индексированный массив с помощью
                    конструкции <type>Array</type>, завершающий пробел должен
                    быть добавлен после каждой запятой для улучшения
                    читабельности:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
]]></programlisting>

                <para>
                    Также разрешается определять многострочные индексированные
                    массивы, используя конструкцию "array". В этом случае,
                    каждая следующая строка должна быть дополнена пробелами
                    так, чтобы начало каждой строки было выравнено как показано
                    ниже:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);
]]></programlisting>

                <para>
                    В качестве альтернативы, начальный элемент может располагаться на следующей
                    строке. В этом случае он должен быть сдвинут на один уровень отступа больше, чем
                    строка содержащая объявление массива. Все последующие строки должны иметь
                    аналогичный отступ. Закрывающая скобка должна быть на отдельной строке с уровнем
                    отступа, что и строка, содержащая объявление массива:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500,
);
]]></programlisting>

                <para>
                    При использовании последнего способа мы рекомендуем ставить запятую после
                    последнего элемента массива. Это упрощает добавление новых строк и обеспечивает
                    отсутствие ошибок из-за пропущенной запятой.
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.arrays.associative">
                <title>Ассоциативные массивы</title>

                <para>
                    Когда определяется ассоциативный массив с помощью
                    конструкции <type>Array</type>, приветствуется разделение выражения на
                    несколько строк. В этом случае, каждая следующая строка
                    должна быть дополнена с помощью пробелов так, чтобы и ключи
                    и значения были выровнены:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
]]></programlisting>

                <para>
                    В качестве альтернативы, начальный элемент может располагаться на следующей
                    строке. В этом случае он должен быть сдвинут на один уровень отступа больше, чем
                    строка содержащая объявление массива. Все последующие строки должны иметь
                    аналогичный отступ. Закрывающая скобка должна быть на отдельной строке с уровнем
                    отступа, что и строка, содержащая объявление массива.
                    Для удобочитаемости, "=>" должен быть выравнен пробелами относительно остальных:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);
]]></programlisting>

                <para>
                    При использовании последнего способа мы рекомендуем ставить запятую после
                    последнего элемента массива. Это упрощает добавление новых строк и обеспечивает
                    отсутствие ошибок из-за пропущенной запятой.
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.classes">
            <title>Классы</title>

            <sect3 id="coding-standard.coding-style.classes.declaration">
                <title>Определение класса</title>

                <para>
                    Классы должны быть именованы согласно схеме именования Zend Framework.
                </para>

                <para>
                    Фигурная скобка всегда пишется на следующей строке под
                    именем класса.
                </para>

                <para>
                    Каждый класс должен иметь блок документации (doc-блок) в
                    соответствии со стандартом PHPDocumentor.
                </para>

                <para>
                    Код внутри класса должен иметь отступ в четыре пробела.
                </para>

                <para>
                    Только один класс разрешен внутри одного <acronym>PHP</acronym>-файла.
                </para>

                <para>
                    Размещение дополнительно кода в файле с классом разрешено,
                    но не приветствуется. В таких файлах, две пустые строки
                    должны разделять класс и дополнительный <acronym>PHP</acronym>-код.
                </para>

                <para>
                    Это пример допустимого определения класса:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Doc-блок здесь
 */
class SampleClass
{
    // содержимое класса должно быть
    // с отступом в четыре пробела
}
]]></programlisting>

                <para>
                    Классы, расширяющие другие классы или реализующие интерфейсы, должны объявлять
                    свои зависимости на той же строке, если возможно.
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass extends FooAbstract implements BarInterface
{
}
]]></programlisting>

                <para>
                    Если в результате такого объявления, длина строки превышает <link
                        linkend="coding-standard.php-file-formatting.max-line-length">максимальную
                    длину строки</link>, сделайте перенос перед ключевыми словами "extends" и/или
                    "implements" и сделайте отступ в один уровень.
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass
    extends FooAbstract
    implements BarInterface
{
}
]]></programlisting>

                <para>
                    Если класс реализует несколько интерфейсов и объявление превышает максимальную
                    длину строки - сделайте перенос после запятой, разделяющей интерфейсы, и
                    выровняйте их имена пробелами:
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass
    implements BarInterface,
               BazInterface
{
}
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.classes.member-variables">
                <title>Переменные-члены классов</title>

                <para>
                    Переменные-члены классов должны быть именованы согласно схеме именования Zend
                    Framework.
                </para>

                <para>
                    Любые переменные, определенные в классе, должны быть
                    определены в начале класса, до определения любого метода.
                </para>

                <para>
                    Ключевое слово <emphasis>var</emphasis> не разрешено. Члены класса
                    должны всегда определять их область видимости, используя
                    ключевое слово <property>private</property>, <property>protected</property>
                    или <property>public</property>. К публичным переменным-членам
                    класса доступ напрямую разрешен, но не приветствуется в пользу методов
                    доступа (set &amp; get).
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.functions-and-methods">
            <title>Функции и методы</title>

            <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
                <title>Определение функций и методов</title>

                <para>
                    Функции должны должны быть именованы согласно схеме именования Zend
                    Framework.
                </para>

                <para>
                    Функции внутри классов должны всегда определять свою область
                    видимости с помощью одного из префиксов <property>private</property>,
                    <property>protected</property> или <property>public</property>.
                </para>

                <para>
                    Как и у классов, фигурная скобка всегда пишется на
                    следующей строке под именем функции. Пробелы между именем
                    функции и круглой скобкой для аргументов не допускаются.
                </para>

                <para>
                    Функции в глобальной области видимости крайне не приветствуются.
                </para>

                <para>
                    Это пример допустимого определения функции:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * Doc-блок здесь
     */
    public function bar()
    {
        // содержимое класса должно быть
        // с отступом в четыре пробела
    }
}
]]></programlisting>

                <para>
                    В случае, если список аргументов превышает <link
                        linkend="coding-standard.php-file-formatting.max-line-length">максимальную
                        длину строки</link>, можно делать перенос строки. Аргументы, перенесенные на
                    следующую строку, должны иметь отступ на один уровень больше чем у объявления
                    метода или функции. Закрывающая скобка должна быть на новой строке с отступом,
                    как у объявления функции/метода, а после нее, через пробел, должна находиться
                    открывающая фигурная скобка. Ниже приведен пример такой ситуации:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * Doc-блок здесь
     */
    public function bar($arg1, $arg2, $arg3,
        $arg4, $arg5, $arg6
    ) {
        // содержимое класса должно быть
        // с отступом в четыре пробела
    }
}
]]></programlisting>

                <note>
                    <para>
                        Передача по ссылке допустима только в определениях функций:
                    </para>
                </note>

                <programlisting language="php"><![CDATA[
/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * Doc-блок здесь
     */
    public function bar(&$baz)
    {}
}
]]></programlisting>

                <para>
                    Передача по ссылке во время вызова строго запрещена.
                </para>

                <para>
                    Возвращаемое значение не должно обрамляться в круглые скобки, иначе это ухудшает
                    читабельность, а также может нарушить код, если метод позже станет возвращать
                    результат по ссылке.
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * ПЛОХО
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * ХОРОШО
     */
    public function bar()
    {
        return $this->bar;
    }
}
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
                <title>Использование функций и методов</title>

                <para>
                   Аргументы функции разделяются одним завершающим пробелом
                   после каждой запятой. Это пример допустимого вызова функции
                   для функции, которая принимает три аргумента:
                </para>

                <programlisting language="php"><![CDATA[
threeArguments(1, 2, 3);
]]></programlisting>

                <para>
                    Передача по ссылке во время вызова запрещена. Смотрите
                    секцию определения функций для правильного способа передачи
                    аргументов функции по ссылке.
                </para>

                <para>
                    Для функций, чьи аргументы допускают массив, вызов функции
                    может включать конструкцию "array" и может быть разделено
                    на несколько строк для улучшения читабельности. В этом
                    случае, применим стандарт описания массивов:
                </para>

                <programlisting language="php"><![CDATA[
threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);

threeArguments(array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500
), 2, 3);
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.control-statements">
            <title>Управляющие структуры</title>

            <sect3 id="coding-standard.coding-style.control-statements.if-else-elseif">
                <title>If / Else / Elseif</title>

                <para>
                    Управляющие структуры, основанные на конструкциях
                    <emphasis>if</emphasis> и <emphasis>elseif</emphasis>, должны иметь один
                    пробел до открывающей круглой скобки условия, и один
                    пробел после закрывающей круглой скобки.
                </para>

                <para>
                    Внутри выражения условия между круглыми скобками
                    операторы должны разделяться пробелами для читабельности.
                    Внутренние скобки приветствуются для улучшения логической
                    группировки больших условий.
                </para>

                <para>
                    Открывающаяся фигурная скобка пишется на той же строке,
                    что и условие. Закрывающаяся фигурная скобка пишется на
                    отдельной строке. Все содержимое между скобками пишется с
                    отступом в четыре пробела.
                </para>

                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}
]]></programlisting>

                <para>
                    Если условное выражение заставляет строку превысить <link
                        linkend="coding-standard.php-file-formatting.max-line-length">максимальную
                        длину строки</link> и имеет несколько условий, вы можете разбить его на
                    несколько строк. В таком случае, делайте перенос до логического оператора и
                    выравнивайте пробелами до первого символа условного выражения. Закрывающая
                    скобка должна быть на новой строке, с уровнем отступа как у управляющей
                    структуры. На той же строке, через пробел, должна находиться открывающая
                    фигурная скобка.
                </para>

                <programlisting language="php"><![CDATA[
if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}
]]></programlisting>

                <para>
                    Цель последнего формата - предотвратить сложности, при добавлении или удалении
                    условий из условного выражения в последующих изменениях.
                </para>

                <para>
                    Для выражения "if", включающего "elseif" или "else",
                    форматирование должно быть таким, как в следующем примере:
                </para>

                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}

if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}

if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
} elseif (($a != $b)
          || ($b != $c)
) {
    $a = $c;
} else {
    $a = $b;
}
]]></programlisting>

                <para>
                    <acronym>PHP</acronym> допускает написание таких выражений без фигурных скобок
                    при некоторых условиях. Стандарт кодирования не делает
                    различий - для всех "if", "elseif" или "else" выражений
                    необходимо использовать фигурные скобки.
                </para>
            </sect3>

            <sect3 id="coding-standards.coding-style.control-statements.switch">
                <title>Switch</title>

                <para>
                    Управляющие структуры, написанные с использованием "switch"
                    конструкции, должны иметь один пробел до открывающей
                    круглой скобки условного выражения, и также один пробел
                    после закрывающей круглой скобки.
                </para>

                <para>
                    Все содержимое между фигурными скобками пишется с отступом
                    в четыре пробела. Содержимое каждого "case" выражения
                    должно писаться с отступом в дополнительные четыре пробела.
                </para>

                <programlisting language="php"><![CDATA[
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}
]]></programlisting>

                <para>
                    Ключевое слово <property>default</property> никогда не должно
                    опускаться в выражении <property>switch</property>.
                </para>

                <note>
                    <para>
                        Иногда полезно писать <property>case</property> выражения, которые передают
                        управление следующему <property>case</property> выражению, опуская
                        <property>break</property> или <property>return</property>. Для того, чтобы
                        отличать такие случаи от ошибок, каждое <property>case</property>
                        выражение, где опущен <property>break</property> или
                        <property>return</property>, должно содержать комментарий, указывающий, что
                        это сделано преднамеренно.
                    </para>
                </note>
            </sect3>
        </sect2>

        <sect2 id="coding-standards.inline-documentation">
            <title>Встроенная документация</title>

            <sect3 id="coding-standards.inline-documentation.documentation-format">
                <title>Формат документации</title>

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

                <para>
                    Все файлы с классами должны содержать doc-блок "уровня файла" и непосредственно
                    перед каждым классом doc-блок "уровня класса". Примеры таких doc-блоков
                    можно увидеть ниже.
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.files">
                <title>Файлы</title>

                <para>
                    Каждый файл, содержащий <acronym>PHP</acronym>-код должен иметь заголовочный
                    doc-блок в начале файла, содержащий как минимум следующие
                    phpDocumentor-теги(для Zend Framework):
                </para>

                <programlisting language="php"><![CDATA[
/**
* Краткое описание файла
 *
 * Длинное описание файла (если есть)
 *
 * LICENSE: информация относительно лицензии
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/
]]></programlisting>

                <para>
                    Тэг <property>@category</property> должен иметь значение "Zend".
                </para>

                <para>
                    Тэг <property>@package</property> должен быть, и иметь значение, соответствующее
                    имени компонента, к которому принадлежит класс. Обычно, имеет только два
                    сегмента: префикс "Zend" и имя компонента.
                </para>

                <para>
                    Тэг <property>@subpackage</property> необязателен. Если предоставлен, должен
                    быть именем подкомпонента минус префикс класса. В примере выше, предполагается,
                    что класс в файле или "<classname>Zend_Magic_Wand</classname>", или использует
                    это имя в качестве части части префикса.
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.classes">
                <title>Классы</title>

                <para>
                    Каждый класс должен иметь doc-блок, содержащий как
                    минимум следующие phpDocumentor-теги:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Краткое описание класса
 *
 * Длинное описание класса (если есть)...
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */
 ]]></programlisting>

                <para>
                    Тэг <property>@category</property> должен иметь значение "Zend".
                </para>

                <para>
                    Тэг <property>@package</property> должен быть, и иметь значение, соответствующее
                    имени компонента, к которому принадлежит класс. Обычно, имеет только два
                    сегмента: префикс "Zend" и имя компонента.
                </para>

                <para>
                    Тэг <property>@subpackage</property> необязателен. Если предоставлен, должен
                    быть именем подкомпонента минус префикс класса. В примере выше, предполагается,
                    что класс в файле или "<classname>Zend_Magic_Wand</classname>", или использует
                    это имя в качестве части части префикса.
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.functions">
                <title>Функции</title>

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

                <itemizedlist>
                    <listitem><para>Описание функции</para></listitem>
                    <listitem><para>Все аргументы</para></listitem>
                    <listitem><para>Все возможные возвращаемые значения</para></listitem>
                </itemizedlist>

                <para>
                    Нет надобности использовать тег "@access", потому что
                    область видимости уже известна из ключевых слов "public",
                    "private" или "protected". используемых при определении
                    функции.
                </para>

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

                <programlisting language="php"><![CDATA[
@throws exceptionclass [описание]
]]></programlisting>
            </sect3>
        </sect2>
    </sect1>
</appendix>
<!--
vim:se ts=4 sw=4 et:
-->