Стандарты кодирования Pear

Тема в разделе "Стиль программирования", создана пользователем GOsha, 21 мар 2007.

  1. GOsha

    GOsha Гость

    Вот вам стандарты PHP-кодирования. Не смотря на то, что он был разработан PEAR для использования в своих целях, следует знать, что очень многое можно использовать и в повседневной работе. Трудно изменить стиль оформления своих работ, не смотря на это, постарайтесь взять в свой стиль программирования как можно больше из этого мануала.
    Ниже прикреплен полный русский PEAR FAQ.
    Для начала давайте узнаем, что такое PEAR?

    PEAR - это аббревиатура от "PHP Extension and Application Repository" (Репозиторий приложений и модулей PHP).

    PEAR - это:
    • структурированная библиотека открытого кода, созданная для пользователей PHP;
    • система управления пакетами и распространения кода среди разработчиков;
    • стандарт написания PHP-кода (подробнее о стандарте см. здесь);
    • базовые классы PHP-кода (подробнее о базовых классах см. здесь;
    • библиотека дополнительных модулей для PHP (The PHP Extension Code Library, PECL), подробную информацию о PECL можно узнать здесь;
    • веб-сайт, листы рассылки и зеркала для загрузки - все это предназначено для поддержания и развития сообщества разработчиков PHP/PEAR.
    Стандарты кодирования PEAR
    Замечание: Стандарты кодирования PEAR используються в коде, который в итоге стает частью PEAR, который в свою очередь поставляеться с дистрибутивом PHP или доступен для скачивания через утилиты инсталяции PEAR.

    --------------------------------------------------------------------------------
    Отступы

    Используйте для отступа 4 пробела, а не табуляцию. Если вы используете Emacs для редактирования кода, вы должны установить indent-tabs-mode в ноль. Ниже приведен пример настройки Emacs для этой цели:
    Код (Text):
    (defun php-mode-hook ()
    (setq tab-width 4
    c-basic-offset 4
    c-hanging-comment-ender-p nil
    indent-tabs-mode
    (not
    (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
    (string-match "\.php$" (buffer-file-name))))))
    А это пример конфигурации для редактора VIM:
    Код (Text):
     set expandtab
    set shiftwidth=4
    set tabstop=4
    --------------------------------------------------------------------------------

    Управляющие структуры
    Управляющие структуры включают в себя операторы if, for, while, switch, и др. Ниже приведен пример оформления оператора if, который в этом отношении является самым сложным:
    Код (Text):
    if ((condition1) || (condition2)) {
    action1;
    } elseif ((condition3) && (condition4)) {
    action2;
    } else {
    defaultaction;
    }
    В управляющих структурах между ключевым словом и открывающей круглой скобкой должен находиться пробел, чтобы отличать их от вызова функций.

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

    Cинтаксис оператора switch:
    Код (Text):
    switch (condition) {
    case 1:
    action1;
    break;

    case 2:
    action2;
    break;

    default:
    defaultaction;
    break;

    }
    --------------------------------------------------------------------------------

    Вызовы функций
    Вызовы функций должны быть написаны без отступв между именем функции, открывающей скобкой и первым параметром. Отступы в виде пробела должны присутствовать после каждой запятой в перечислении параметров. Пробелов также не должно быть между последним параметром, закрывающей скобкой и точкой с запятой. Пример:
    Код (Text):
    $var = foo($bar, $baz, $quux);
    Как можно заметить, в примере используются пробелы с двух сторон от знака "=". Если подобные присвоения результатов функций переменным объединяются в блоки, то для повышения читабельности рекомендуется следующий синтаксис:
    Код (Text):
    $short       = foo($bar);
    $long_variable = foo($baz);
    --------------------------------------------------------------------------------

    Определения функций
    Определения функций следуют такому cоглашению:
    Код (Text):
    function fooFunction($arg1, $arg2 = '')
    {
    if (condition) {
    statement;
    }
    return $val;
    }
    Аргументы функций со значениями по умолчанию должны находиться в конце списка аргументов. Функции всегда должны возвращать значение, если это возможно в принципе. Чуть более подробный пример:
    Код (Text):
    function connect(&$dsn, $persistent = false)
    {
    if (is_array($dsn)) {
    $dsninfo = &$dsn;
    } else {
    $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
    return $this->raiseError();
    }

    return true;
    }
    --------------------------------------------------------------------------------

    Комментарии
    Комментарии внутри кода классов должны соответствовать синтаксису комментариев PHPDoc, который напоминает Javadoc. За дополнительной информацией о PHPDoc обращайтесь сюда: http://www.phpdoc.org/

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

    Подходят комментарии в стилях C (/* */) и C++ (//). Использование комментариев в стиле Perl/shell (#) не рекомендуется.

    --------------------------------------------------------------------------------

    Подключение кода (including)
    В тех местах, где вы используете подключение файлов других классов вне зависимости от условий, используйте конструкцию require_once(). Если же подключение файлов зависит от каких-либо условий, то следует использовать include_once(). В этом случае вы всегда будете уверены в том, что файлы подключаются только единожды.

    Замечание: include_once() и require_once() и являются конструкциями, а не функциями. Вам не обязательно использовать скобки вокруг имени файла, который подключается.

    --------------------------------------------------------------------------------

    Тэги PHP-кода
    Всегда используйте <?php ?> вместо <? ?>для выделения PHP-кода. Это необходимо для обеспечения работы PEAR на разных операционных системах и с различными настройками.

    --------------------------------------------------------------------------------

    Блок комментариев в заголовке
    Все базовые файлы исходного кода в PEAR должны содержать следующий ниже блок комментариев в заголовке:
    Код (Text):
    /* vim: set expandtab tabstop=4 softtabstop=4 shiftwidth=4: */
    // +----------------------------------------------------------------------+
    // | PHP version 4                                                      |
    // +----------------------------------------------------------------------+
    // | Copyright (c) 1997-2002 The PHP Group                              |
    // +----------------------------------------------------------------------+
    // | This source file is subject to version 2.0 of the PHP license,   |
    // | that is bundled with this package in the file LICENSE, and is      |
    // | available at through the world-wide-web at                       |
    // | http://www.php.net/license/2_02.txt.                                |
    // | If you did not receive a copy of the PHP license and are unable to  |
    // | obtain it through the world-wide-web, please send a note to         |
    // | license@php.net so we can mail you a copy immediately.           |
    // +----------------------------------------------------------------------+
    // | Authors: Original Author <author@example.com>                      |
    // |         Your Name <you@example.com>                                 |
    // +----------------------------------------------------------------------+
    //
    // $Id$
    Нет четкого правила, которое определяет момент, когда новый разработчик должен быть добавлен в список авторов данного файла. В общем случае, его внос в изменения этого файла должен относиться к категории "значительных" (т.е. около 10%-20% процентов кода). Исключения могут быть в случае переписывания функций или добавления новой логики.

    Простая реорганизация кода и исправление ошибок не приводит к добавлению нового участника в список авторов.

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

    --------------------------------------------------------------------------------

    Использование CVS
    Эта часть касается только пакетов, использующих CVS на cvs.php.net.

    Включайте ключевое слово CVS - $Id$ в каждый файл. Добавьте эту метку в каждый файл, если там ее еще нет или исправьте уже существующую запись "Last Modified:" и т.п.).

    В оставшейся части этой главы предполагается, что вы имеете представление о тэгах CVS и ветках (branches).

    Тэги CVS предназначены для того, чтобы пометить файлы, которые принадлежат к конкретному релизу. Ниже приводится список необходимых и рекомендуемых тэгов:

    RELEASE_n_n
    (обязательный) Используется для пометки релиза. Если вы не используете его, то вы не сможете вернуться назад и затребовать пакет в том виде, в котором он находился во время прошлого релиза.

    QA_n_n
    (необязательный) Если вы чувствуете, что перед выпуском релиза необходимо выпустить предварительную версию (release candidat), то вы можете сделать ветку (branch) кода для того, чтобы изолировать релиз и вносить только критически важные изменения до релиза. При этом, обычный процесс разработки может продолжаться в основном дереве кода.

    MAINT_n_n
    (необязательный) Если вам нужно сделать "микро-релиз" (например, версию 1.2.1 и т.п. после 1.2), вы так же можете использовать ветку в том случае, если основной код меняется достаточно активно и вы хотите вносить только небольшие изменения в микро-релизы.

    Обязательным является только тэг RELEASE, остальные рекомендуются для вашего же удобства.

    Пример того, как пометить тэгом релиза 1.2 пакет "Money_Fast":
    Код (Text):
    $ cd pear/Money_Fast
    $ cvs tag RELEASE_1_2
    T Fast.php
    T README
    T package.xml
    Сделав так, вы получаете возможность использовать веб-сайт PEAR для дальнейшего процесса выпуска релизов.

    Пример создания ветки для QA:
    Код (Text):
    $ cvs tag QA_2_0_BP
    ...
    $ cvs rtag -b -r QA_2_0_BP QA_2_0
    $ cvs update -r QA_2_0
    $ cvs tag RELEASE_2_0RC1
    ...далее, создаем настоящий релиз из то же ветки:
    $ cvs tag RELEASE_2_0
    Тэг "QA_2_0_BP" - это тэг ветки. Рекомендуется всегда выделять ветки этим тэгом. Служебные ветви (MAINT branches) могут быть отмечены как релиз и без использования этого тэга.

    --------------------------------------------------------------------------------

    Примеры URLов
    Используйте "example.com" для примеров URLов, как описано в RFC 2606.

    --------------------------------------------------------------------------------

    Соглашения об именах
    В общем случае, имена классов, функций и переменных всегда должны быть "говорящими" для того, чтобы читатель мог сразу понять для чего они используются.

    --------------------------------------------------------------------------------

    Классы
    Имена классов должны быть удобочитаемыми и понятными. Избегайте использования аббревиатур там, где это возможно. Имена классов должны начинаться с буквы в верхнем регистре. Иерархия классов PEAR также отражается на именах классов, каждый уровень отделяется знаком подчеркивания. Примеры хороших имен классов:
    Код (Text):
    Log
    Код (Text):
    Net_Finger
    Код (Text):
    HTML_Upload_Error
    --------------------------------------------------------------------------------

    Функции и методы
    Функции и методы должны использовать "венгерскую нотацию" (в другом варианте - "верблюжачью" =)). Функции также должны иметь префикс в виде имени пакета для того, чтобы избежать проблем с аналогичными функциями из других пакетов. Первая буква в имени функции должна быть в нижнем регистре, каждая первая буква "слова" в имени функции - в верхнем. Несколько примеров:
    Код (Text):
    connect()
    Код (Text):
    getData()
    Код (Text):
    buildSomeWidget()
    Код (Text):
    XML_RPC_serializeData()
    Приватные методы и свойства (те методы и атрибуты, которые используются только внутри самого класса; PHP пока(?) не поддерживает их настоящее выделение) должны быть префиксированы знаком подчеркивания. Например:

    Код (Text):
    _sort()
    Код (Text):
     _initTree()
    Код (Text):
    $this->_status
    --------------------------------------------------------------------------------

    Константы
    Имена констант всегда должны быть в верхнем регистре с подчеркиваниями для разделения слов. В качестве префикса в именах констант должно использоваться имя пакета/класса, в котором они используются. Например, все константы, которые используются в пакете DB::, начинаются с "DB_".

    --------------------------------------------------------------------------------

    Глобальные переменные
    Если в вашем пакете необходимо объявить глобальные переменные, то их имя должно начинаться с подчеркивания, имени пакета и еще одного пакета. Например, пакет PEAR использует глобальную переменную, которая называется $_PEAR_destructor_object_list.

    --------------------------------------------------------------------------------

    Встроенные переменные TRUE, FALSE, NULL
    Встроенные переменные PHP TRUE, FALSE and NULL должны быть написаны в нижнем регистре.

    --------------------------------------------------------------------------------
     

    Вложения:

  2. DolWeb

    DolWeb Гость

    Мне понравилась статейка :huh:
     
  3. GOsha

    GOsha Гость

    ГЫГ... ))) Долго клацал.
     
Загрузка...
Похожие Темы - Стандарты кодирования Pear
  1. fedotxxl
    Ответов:
    5
    Просмотров:
    3.341
  2. slavon-x86
    Ответов:
    7
    Просмотров:
    5.276

Поделиться этой страницей