Статья - Стандарты кодирования Pear | Форум информационной безопасности

Вот вам стандарты 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 для этой цели:

Код:

(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;
}

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

Код:

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 обращайтесь сюда:

Ссылка скрыта от гостей

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

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

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

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

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

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

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

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

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

Код:

/* 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()

Код:

XML_RPC_serializeData()

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

Код:

_sort()

Код:

 _initTree()

Код:

$this->_status

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

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

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

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

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

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

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

Нажмите, чтобы раскрыть...

Все сервисы Codeby

Поиск

Поиск

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

Вложения

DolWeb

GOsha

GusBot

Заблокирован

Mozzy