Permalink
Find file
878b2c5 Jul 2, 2013
@rtretyakov @getjump @pmjones
158 lines (101 sloc) 7.44 KB

Основной стандарт написания кода

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

Ключевые слова «ОБЯЗАН», «НЕ ОБЯЗАН», «НЕОБХОДИМ», «ЖЕЛАТЕЛЕН», «НЕ ЖЕЛАТЕЛЕН», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «РЕКОМЕНДОВАН», «ВЕРОЯТЕН», и «ОПЦИОНАЛЕН» в этом документе СЛЕДУЕТ интерпретировать в соответствии с RFC 2119.

1. Обзор

  • Файлы ДОЛЖНЫ использовать в качестве открывающих тегов только <?php и <?=.

  • Файлы ДОЛЖНЫ использовать только кодировку «UTF-8 без BOM» ("UTF-8 without BOM") для PHP-кода.

  • В файлы СЛЕДУЕТ либо объявлять символы (классы, функции, константы и т.д.) либо вызывать побочные эффекты (например генерировать вывод, менять настройки .ini и т.д.), но НЕ СЛЕДУЕТ делать и то и другое.

  • Пространства имен и классы ДОЛЖНЫ следовать PSR-0.

  • Имена классов ДОЛЖНЫ определяться в StudlyCaps.

  • Константы классов ДОЛЖНЫ определяться со всеми символами в верхнем регистре с символами подчеркивания.

  • Названия методов ДОЛЖНЫ определяться в camelCase.

2. Файлы

2.1. Теги PHP

PHP код ОБЯЗАН использовать длинный тег <?php ?> или короткий тег <?= ?> для краткого вывода информации; он ОБЯЗАН НЕ ИСПОЛЬЗОВАТЬ другие вариации тегов.

2.2. Кодировка символов

PHP код ОБЯЗАН использовать кодировку «UTF-8 без BOM» ("UTF-8 without BOM").

2.3. Побочные эффекты

Файл ДОЛЖЕН объявлять новые символы (классы, функции, константы, и т.д..) и не вызывать побочные эффекты, или же ДОЛЖЕН лишь выполнять логику с побочными эффектами, но НЕ ДОЛЖЕН реализовывать оба действия.

Фраза «побочный эффект» означает выполнение логики, которая не относится напрямую к объявлению классов, функций, констант и т.д., простое подключение файлов

«Побочный эффект» включает, но не ограничивается: генерацией вывода, явное использование require или include, подключение к внешним сервисами, модификация настроек ini, выдавать ошибки или исключения, изменять глобальные или статичные переменные, чтение или запись в файл, и т.д.

Ниже представлен пример файла вместе с декларацией и побочными эффектами; этот код является примером того, чего следует избегать (код является неправильным):

<?php
// Побочный эффект: изменение настроек ini
ini_set('error_reporting', E_ALL);

// Побочный эффект: загрузка файла
include "file.php";

// Побочный эффект: генерация вывода
echo "<html>\n";

// Объявление функции
function foo()
{
    // тело функции
}

Следующий пример файла содержит объявление без побочных эффектов; этот код является правильным;

<?php
// Объявление функции
function foo()
{
    // Тело функциии
}

// Условное объявление *не является* побочным эффектом
if (! function_exists('bar')) {
    function bar()
    {
        //Тело функции
    }
}

3. Пространства имен и названия классов

Пространства имен и классы ДОЛЖНЫ следовать PSR-0.

Это значит, что каждый класс — это файл, не больше, не меньше, и в пространстве имен, как минимум один уровень: верхний уровень «наименование производителя».

Названия классов ДОЛЖНЫ быть объявленными в StudlyCaps.

Код, написанный для PHP 5.3 и выше, ОБЯЗАН использовать формальные пространства имен.

Например:

<?php
// PHP 5.3 и выше:
namespace Vendor\Model;

class Foo
{
}

Код, написанный для PHP 5.2.x и ниже, ДОЛЖЕН использовать псевдо конвенцию пространств имен, начиная с Наименования_Производителя_ в названиях классов.

<?php
// PHP 5.2.x и ниже:
class Vendor_Model_Foo
{
}

4. Константы Классов, Свойства, и Методы

Термин «класс» относится ко всем классам, интерфейсам и трейтам.

4.1. Константы

Константы классов ДОЛЖНЫ быть именованными символами верхнего регистра вместе с разделителями (символами подчеркивания).

Например:

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

4.2. Свойства

Это руководство намеренно избегает рекомендаций относительно использования $StudlyCaps, $camelCase, или $under_score в названиях свойств.

Как бы то ни было, используемый стандарт именования ДОЛЖЕН применяться последовательно в разумных пределах. Этот предел может быть установлен на уровне производителя, пакета, класса, или метода.

4.3. Методы

Названия Методов ДОЛЖНЫ быть объявлены в camelCase().