Отправляет email-рассылки с помощью сервиса Sendsay

PHP 5: Новые возможности.

Рассылка закрыта

При закрытии подписчики были переданы в рассылку "Заметки Дизайнера" на которую и рекомендуем вам подписаться.

Вы можете найти рассылки сходной тематики в Каталоге рассылок.

←   Январь 2006   →
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Автор
ImHoster.net

Статистика

1.046 подписчиков
-2 за неделю
←   Все выпуски   →

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


Информационный Канал Subscribe.Ru

PHP 5: Новые возможности.

The Pterodactyl

Copyright 2005 Pterodactyl's School

04.01.2006

История переиздания
Издание 1.00 04.01.2006
Первоначальная версия.

Аннотация

Изложены основные правила оформления кода, принятые в PEAR. Отмечены особенности применения этих правил в PHP 5.

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

Полное описание стандартов

Отступы (indents) используются для форматирования кода. Плохо форматированный код гораздо труднее воспринимается визуально (Пример 1, «Плохой стиль кодирования»). Такой код очень тяжело дорабатывать, исправлять и т. д. Более того, при работе с таким кодом гораздо легче допустить ошибку. Сравните, насколько привлекательнее выглядит тот же самый код в отформатированном виде (Пример 2, «Форматированный код»).

Пример 1. Плохой стиль кодирования 

<?php
switch ($var) {
case 'F1':
print 'Help Me!';
break;
case: 'F3':
print 'View';
break;
case: 'F4':
print 'Edit';
break;
default:
print 'Unknown variable.';
}
?>

Пример 2. Форматированный код 

<?php
    switch ($var) {
        case 'F1':
            print 'Help Me!';
            break;
        
        case: 'F3':
            print 'View';
            break;
        
        case: 'F4':
            print 'Edit';
            break;
        
        default:
            print 'Unknown variable.';
    }
?>

В PEAR принято очень простое и четкое правило: используйте отступ, равный четырем пробелам, без табуляции.

Подсказка

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

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

Длина строки должна в среднем составлять 75..85 символов. Со слишком длинными строками неудобно работать. Старайтесь укладываться в названные рамки, даже если используемый Вами редактор автоматически разбивает длинные строки при их отображении в окне редактирования. Помните, что когда-нибудь Вам самим или кому-нибудь другому, возможно, придется работать с Вашим кодом в более простом редакторе.

Для демонстрации правил оформления контрольных структур[1] воспользуемся наиболее сложной структурой - if/elseif/else (Пример 3, «Форматирование контрольной структуры if/elseif/else»). Контрольная структура switch была рассмотрена ранее (Пример 2, «Форматированный код»).

Правила оформления контрольных структур

  • Между ключевым словом (if, else, for, switch и т. п.) и открывающей круглой скобкой должен находиться один пробел для отличия контрольных структур от функций.
  • Следует всегда использовать фигурные скобки, даже в тех случаях, когда условный блок состоит лишь из одной строки и их можно было бы опустить. Это делает код более читабельным и уменьшает риск возникновения ошибок при добавлении новых строк.
  • Открывающая фигурная скобка находится в одной строке с условием[2], и это тоже отличает контрольные структуры от функций.
  • Ключевые слова elseif, else находятся в одной строке с фигурной скобкой, закрывающей предыдущий условный блок.

  • Если условие состоит из нескольких выражений, то каждое из них заключается в круглые скобки, как показано ниже.

    if (($a == $b) || ($c < $d)) { /* ... */ }

    Но:

    $s1 = ($a == $b); $s2 = ($c < $d); if ($s1 || $s2) { /* ... */ }

Пример 3. Форматирование контрольной структуры if/elseif/else 

<?php
    if (($a == $b) || ($c < $d)) {
        print 'If';
    } elseif ($e != $f) {
        print 'Else If';
    } else {
        print 'Else';
    }
?>

При определении и вызове функций необходимо соблюдать следующие правила (Пример 4, «Определение и вызов функции»).

Правила определения функций

  • Между именем функции, открывающей круглой скобкой и первым аргументом не должно быть пробелов.
  • Аргументы, имеющие значения по умолчанию, должны указываться последними.
  • Открывающая и закрывающая фигурные скобки располагаются по левому краю (под буквой 'f'), каждая в отдельной строке.
  • Остальной код функции должен иметь отступ.
  • Функция всегда должна возвращать какое-нибудь значение, если только это технически возможно[3], хотя бы для индикации успешности своего завершения.

Правила вызова функций

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

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

    Замечание

    Если имеет место серия взаимосвязанных присвоений, то допускается большее количество пробелов для выравнивания:

    <?php
    $a      = foo($bar);
    $a_1001 = foo($var);
?>

Пример 4. Определение и вызов функции 

<?php
    function foo($a, $b = 0, $c = '')
    {
        // ...
        
        return TRUE;
    }

    $a = foo($bar, $var);
?>

Символьные имена элементов языка разных типов следуют различным схемам, чтобы элементы одного типа отличались от элементов другого.

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

Методы. Названия методов классов должны начинаться со строчной буквы; все последующие слова в названии начинаются с заглавной буквы. Аббревиатуры, которые обычно пишутся в верхнем регистре, используются в названиях в неизмененном виде. Названия приватных методов должны начинаться со знака подчеркивания. Однако, в PHP 5 такие методы будут на самом деле публичными, поэтому следует использовать модификатор private без знака подчеркивания. Например: addUser, toHTML, _loadStorage (в PHP 5 - private function loadStorage).

Функции. Функции должны использовать полное имя пакета, к которому они принадлежат, в качестве префикса, после которого, отделенное знаком подчеркивания, следует собственно название функции. Это название должно начинаться со строчной буквы; все последующие слова в названии начинаются с заглавной буквы. Названия функций, предназначенных для использования только внутри пакета, к которому они принадлежат (аналог приватных методов класса), должны начинаться со знака подчеркивания; при этом использование префикса становится нецелесообразным ввиду отсутствия риска возникновения конфликта имен с другим пакетом. Например: XML_RPC_encode (из пакета XML_RPC), XML_RPC_Server_listMethods (из пакета XML_RPC_Server), _uppercaseCallback (приватная функция из набора тестов для пакета HTML_Template_IT).

Переменные клвссов. Единственным требованием является наличие знака подчеркивания в начале приватных переменных класса. Однако, в PHP 5 предпочтительнее использовать модификатор private. Например: $_sessionName (в PHP 5 - private $sessionName).

Глобальные переменные. Название глобальной переменной должно состоять из двух частей: имени пакета, в который она входит, отделенному с двух сторон знаками подчеркивания; и собственно имени самой переменной, написанному строчными буквами (например, $_PEAR_destructor_object_list). В PHP 5 вместо глобальных переменных можно использовать статические переменные класса.

Константы. Константы всегда пишутся заглавными буквами, со знаком подчеркивания между отдельными словами; в качестве префикса используется название пакета, к которому они относятся: PEAR_ERROR_CALLBACK, AUTH_WRONG_LOGIN, HTML_MENU_ENTRY_ACTIVE и т. п. В PHP 5 можно также использовать class const переменные. Обращаться к ним следует по правильно написанному имени пакета и имени самой переменной в верхнем регистре (без префикса): PEAR::ERROR_CALLBACK, Auth::WRONG_LOGIN, HTML_Menu::ENTRY_ACTIVE и т. п.

Замечание

Константы true, false, null являются исключением и всегда пишутся строчными буквами.

Формат файлов. Все скрипты должны быть сохранены как ASCII текст; должна использоваться кодировка ISO-8859-1[4]; для разделения строк используется одиночный символ перевода строки (LF - код 0x0A), но не возврат каретки (CR) или их сочетание (CRLF); после закрывающего тэга ?> должен следовать один перевод строки.

Тэги PHP кода. Для ограничения PHP кода следует всегда использовать <?php ?> вместо <? ?>. Это обеспечит большую совместимость и платформенную независимость кода.

Комментарии. Наличие встроенной документации (/** */) является обязательным (см. Приложение A, Практикум). Приветствуются также обычные комментарии в стиле C и C++ (/* */ и //). Нежелательно использовать комментарии в стиле Perl (#).

Адреса в примерах. В примерах используйте для URL и адресов электронной почты example.com, example.org и example.net.

A. Практикум

Как уже было сказано, каждый скрипт должен содержать встроенную документацию - специальную разновидность комментариев (/** */). В частности, такие комментарии впоследствии могут распознаваться специальными приложениями при автоматическом создании общей документации к разрабатываемому проекту.

В частности, каждый файл должен иметь в самом начале один заголовочный блок "страничного" уровня (Пример A.1, «Шаблон для будущих скриптов»); аналогичный блок должен предшествовать каждому классу. Как правило, блоками документации предваряют также переменные и методы класса.

Создадим шаблон заголовка, который, после незначительной правки, можно будет в дальнейшем использовать для скриптов нашего учебного проекта Simple Site Solution (Простое Решение для Сайта).

Пример A.1. Шаблон для будущих скриптов 

<?php

/**
 * A part of the Simple Site Solution package
 *
 * PHP version 5
 *
 * LICENSE: This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * @package    SSS
 * @author     The Pterodactyl <ptero@pterodactyl.l2p.net>
 * @copyright  2006 Pterodactyl's School
 * @license    http://www.gnu.org/licenses/gpl.txt  GNU General Public License
 * @version    0.00
 * @link       http://pterodactyl.l2p.net/php5/examples/SSS
 */

?>

На сайте файл с этим кодом находится здесь.

Created with DocBook Created with Libxslt


[1] Термин "контрольная структура" вместо более распространенного "управляющая структура" здесь и далее употребляется вполне осознанно как близкий по смыслу последнему, но куда более созвучный оригиналу (control structure).

[2] Стиль Кернигана и Ричи, или K&R.

[3] Конструктор класса, например, вообще ничего не возвращает.

[4] В случае разработки локализованных приложений строго соблюсти данное требование не представляется возможным. Мы будем стремиться к написанию основных скриптов в кодировке ISO-8859-1, а все локальные строки выносить во внешние файлы ресурсов.

С последней версией этой и других статей Вы можете ознакомиться на сайте рассылки [http://pterodactyl.l2p.net/php5/].

Subscribe.Ru
Поддержка подписчиков
Другие рассылки этой тематики
Другие рассылки этого автора		 Подписан адрес:
Код этой рассылки: inet.webbuild.php5whatsnew
Архив рассылки		 Отписаться Вебом Почтой
Вспомнить пароль
В избранное