Web - кодинг: PHP:

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

Материал взят с сайта:

Замечание: Стандарты кодирования PEAR используются в коде, который в итоге станет частью PEAR, который в свою очередь поставляется с дистрибутивом PHP или доступен для скачивания через утилиты инсталляции PEAR.
Отступы
Используйте для отступа 4 пробела, а не табуляцию. Если вы используете Emacs для редактирования кода, вы должны установить indent-tabs-mode в ноль. В листинге 1 приведен пример настройки Emacs для этой цели:

Листинг 1

(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:
set expandtab set shiftwidth=4 set tabstop=4

Управляющие структуры

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

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

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

Cинтаксис оператора switch:

switch (condition) { case 1: action1; break; case 2: action2; break; default: defaultaction; break; }

Вызовы функций

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

Определения функций

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

Листинг 2

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

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

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

Подключение кода (including)

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

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

Тэги PHP-кода

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

Блок комментариев в заголовке

Все базовые файлы исходного кода в PEAR должны содержать следующий ниже блок комментариев в заголовке (листинг 3):

Листинг 3

/* 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":

$ cd pear/Money_Fast $ cvs tag RELEASE_1_2 T Fast.php T README T package.xml

Сделав так, вы получаете возможность использовать веб-сайт PEAR для дальнейшего процесса выпуска релизов.

Пример создания ветки для QA:

$ 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 также отражается на именах классов, каждый уровень отделяется знаком подчеркивания. Примеры хороших имен классов:

Log Net_Finger HTML_Upload_Error

Функции и методы

Функции и методы должны использовать "венгерскую нотацию" (в другом варианте - "верблюжачью" =)). Функции также должны иметь префикс в виде имени пакета для того, чтобы избежать проблем с аналогичными функциями из других пакетов. Первая буква в имени функции должна быть в нижнем регистре, каждая первая буква "слова" в имени функции - в верхнем. Несколько примеров:

connect() getData() buildSomeWidget()

Приватные методы и свойства (те методы и атрибуты, которые используются только внутри самого класса; PHP пока(?) не поддерживает их настоящее выделение) должны быть префиксированы знаком подчеркивания. Например:

_sort() _initTree() $this->_status

Константы

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

Глобальные переменные

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

Встроенные переменные TRUE, FALSE, NULL

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

При перепечатке любого материала с сайта, видимая ссылка на источник www.warayg.narod.ru и все имена, ссылки авторов обязательны.

© 2005