Developers/Coding Standard/ru

Стандарты кодирования Arcavias основываются на Стандартах кодирования Zend. Воспользуйтесь нашей шпаргалкой для ознакомления со стандартами кодирования Arcavias.

Форматирование файлов

 * Не должно быть закрывающего тега PHP ?>;
 * для отступов используется таблуяция (без пробелов!);
 * максимальная длина строки должна быть 120 символов;
 * переводы строк в стиле Unix: LF (ASCII / UTF-8 символ 10 в десятеричной системе, 0x0A в шестнадцатиричной);
 * кодировка исходного кода UTF-8 без маркера последовательности байтов (BOM).

Настройки Eclipse
Инструкции справедливы для версии Eclipse 3.7.2 (Indigo)


 * Use tabs instead of spaces:
 * menu bar -> Window -> Preferences -> PHP -> Code Style -> Formatter -> Tab policy: Tabs
 * menu bar -> Window -> Preferences -> General -> Editors -> Text Editors -> Insert spaces for tabs: uncheck box
 * Set UTF-8 as default encoding:
 * menu bar -> Window -> Preferences -> General -> Workspace -> Text file encoding -> Other: UTF-8
 * Set line feed as default line delimiter:
 * menu bar -> Window -> Preferences -> General -> Workspace -> New text file line delimiter -> Other: Unix

Файлы, классы, интерфейсы

 * названия классов должны отражать путь к директории соответствующего файла: класс  должен быть определён в    (смотрите PSR-0 стандарт);
 * в файле должен быть лишь один класс;
 * первая буква каждого слова — заглавная;
 * последующие буквы должны быть в нижнем регистре (то есть, Горбатый Синтаксис для названий);
 * слова разделяются подчёркиваниями;
 * названия абстрактных классов должны закачиваться на Abstract:
 * названия интерфейсов должны закачиваться на Interface:
 * названия остальных файлов должны содержать лишь символы латинского алфавита, цифры, подчёркивания и дефис (без пробелов!).

Методы, переменные и константы

 * Допустимы лишь символы латинского алфавита, цифры недопустимы.
 * Подчёркивания допускаются только в качестве префикса к декларации свойств private, декларации названий методов private / protected</tt> и внутри названий констант.
 * Методы private</tt> / protected</tt> и свойства private</tt> должны быть с префиксом подчёркивания (смотрите также область видимости для методов и свойств):


 * Названия методов и переменный пишутся в lowerCamelCase</tt>:,   и должны быть описательными.
 * set</tt> и get</tt> должны использоваться в виде префиксов для методов доступа к свойства объекта:,.
 * Константы записываются заглавными буквами, слова отделяются подчёркиваниями:

Структура файлов и классов

 * Файл, класс и метод — документация обязательна.
 * Блок doc файла должен состоять из @copyright</tt>, @license</tt>, @package</tt> и @subpackage</tt>.
 * Блок doc класса должен состоять из @package</tt> и @subpackage</tt>.
 * Блок doc методов должен включать @param</tt>, @return</tt> и @throws</tt>, если применимо.
 * Все блоки документации должны быть совместимы с форматом phpDocumentor (http://www.phpdoc.org).

Полный пример файла выглядит как в примере ниже (только один класс в файле). Все строки с комментариями <tt>//</tt> служат только для описания и не должны являться частью исходного кода.


 * Обратите внимание на пробелы, почти везде используется один в качестве разделителя.
 * Исключения: нет пробелов между названиями метода и круглой скобкой:
 * Отдельная строка для фигурных скобок классов и методов.
 * Свойства класса должны быть только <tt>private</tt>.
 * Методы всегда должны указывать область видимости ключевыми словами <tt>public</tt>, <tt>protected</tt> или <tt>private</tt> (смотрите также область видимости).
 * По возможности необходимо указывать подсказки по типу.
 * Описания методов должны быть написаны в упрощённом представлении.
 * По возможности, классы должны декларировать свои зависимости в одной строке.

Строки и массивы
Замечание: Пробелы используются повсеместно для лучшей читаемости!


 * Строки всегда в одинарных кавычках: !
 * Используйте  для каждой подстановки переменной, так как это лучше поддерживает локализацию.


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


 * Ассоциативные массивы должны быть записаны в несколько строк.
 * Пары ключ / значение имеют отступ в одну табуляцию.
 * Для ассоциативных массивов используйте пробелы до и после оператора "=>".

Управляющие операторы
Замечание: Пробелы используются повсеместно для лучшей читаемости!


 * Следующие правила применимы ко всем управляющим структурам где это возможно, например, где используются скобки, вроде <tt>if/else</tt>, <tt>switch</tt>, <tt>while</tt>, <tt>for</tt>, <tt>foreach</tt> and <tt>try/catch</tt>.
 * Фигурные скобки обязательны для всех управляющих операторов.
 * Для тестирования эквивалентности значений всегда используйте оператор <tt>===</tt>, так как при этом учитывается и тип переменной, в отличие от <tt>==</tt>, где учитывается лишь эквивалентность значений, что может привести к неожиданным эффектам.
 * Фигурные скобки в операторах if находятся на одной строке с ключевыми словами <tt>if</tt> / <tt>else</tt>.
 * Содержимое записывается с отступом в одну табуляцию.
 * Закрывающие скобки уравниваются с <tt>if</tt>.


 * Фигурные скобки многострочного оператора if всегда располагаются на одной строчке.
 * Для содержимого делается отступ в одну табуляцию.
 * Закрывающая фигурная скобка выравнивается с <tt>if</tt>.


 * Оператор if со сложными условиями может занимать несколько строк.
 * Вторые и последующие условия делаются с отступом в одну табуляцию.
 * Для содержимого также делается отступ в одну дополнительную табуляцию.


 * Фигурные скобки для оператора switch всегда пишутся на той же строке.
 * Операторы Case указываются с дополнительным отступом на одну табуляцию.
 * Содержимое и операторы break даются с отступом в две табуляции.
 * Закрывающая фигурная скобка выравнивается по ключевому слову <tt>switch</tt>.

Шпаргалка
Для быстрого просмотра прекрасно подходит наша шпаргалка. Она приведена в двух версиях — цветная и чёрно-белая:


 * [[Media:Cheat_Sheet_colored.pdf|Шпаргалка (цветная)]]
 * [[Media:Cheat_Sheet_bw.pdf|Шпаргалка (ч/б)]]

Смотрите также

 * http://framework.zend.com/manual/1.12/en/coding-standard.html
 * http://www.phpdoc.org