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

Автор: Aport Суббота, Январь 31st, 2015 Нет комментариев

Рубрика: Язык PHP

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

Содержание

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

Общее

Для файлов, содержащих только PHP-код, закрывающийся тег («?>«) не разрешен. Он не требуется синтаксисом PHP. Это предотвращает от случайного включения в вывод конечных пробелов.

Отступы

Для отступа используйте 2 пробела. Не используйте символ табуляции. Использование двух пробелов позволяет экономить горизонтальное пространство при большом вложении программных блоков.

Максимальная длина строки

Рекомендуемая длина строки составляет 80 символов, т.е. разработчики должны стремиться держать код как можно ближе к 80-символьной границе, когда это возможно. Однако более длинные строки также допустимы. Максимальная длина любой строки PHP-кода не должна превышать 120 символов.

Соглашение по именованию

Пространства имен

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

Имена пространств могут содержать только буквенно-числовые символы. Числа допустимы в именах, но не приветствуются. Если имя пространства состоит из более чем одного слова, то первая буква каждого слова должна быть заглавной, например, «Space\GoodStyle«. Последующие заглавные буквы недопустимы.

Ниже приведен пример именования пространства и указания директории, в которой должны располагаться включаемые в пространство объекты:

Space\Subspace – Space/Subspace

Классы

Для именования классов используется схема, в соответствии с которой имена классов напрямую указывают на файл, в котором описан класс.

Имена классов могут содержать только буквенно-числовые символы. Числа допустимы в именах классов, но не приветствуются. Если имя класса состоит из более чем одного слова, то первая буква каждого слова должна быть заглавной, например, «OrderPrint«. Последующие заглавные буквы недопустимы.

Ниже приведены примеры допустимых имен классов с указанием пространства имен:

Space\Subspace\Class
Skeleton\Gpachic\Image

Интерфейсы

Интерфейсы должны следовать той же схеме именования, как и классы (смотрите выше):

Space\Subspace\Interface

Имена файлов

Для файлов допустимы буквенно-числовые символы, символы нижнего подчеркивания и тире («-«). Пробелы запрещены.

Любой файл, содержащий только PHP-код, должен иметь расширение «.php«. Эти примеры показывают допустимые имена файлов для классов из примеров в секции выше:

Space/Subspace/Class.php
Skeleton/Gpachic/Image.php
Space/Subspace/Interface.php

Имена файлов отражаются на имена классов, как описано выше.

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

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

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

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

Это примеры допустимых имен функций:

filterInput()
getElementById()
widgetFactory()

Функции в глобальной области видимости («плавающие функции«) допустимы, но не приветствуются. Рекомендуется обрамлять такие функции в статические классы.

Переменные

Имена переменных могут содержать буквенно-числовые символы. Символы нижнего подчеркивания не разрешены. Числа разрешены в именах переменных, но не приветствуются. Определение переменных – членов класса, с помощью префикса области видимости «public» не приветствуется в пользу использования методов, для организации доступа к этой переменной.

Как и имена функций (смотрите секцию выше) имена переменных должны начинаться с буквы в нижнем регистре и следовать «верблюжьей» нотации.

Многословность приветствуется. Имена переменных должны быть настолько говорящими, насколько это практично. Краткие имена переменных, такие как «$i» и «$n» не приветствуются нигде, кроме как в контексте маленьких циклов. Если цикл содержит более 20 строк кода, то переменные для индексов должны иметь более говорящие имена.

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

Константы

Константы могут содержать буквенно-числовые символы и символы нижнего подчеркивания. Числа разрешены в именах констант.

Имена констант должны быть в верхнем регистре.

Константы должны быть определены как члены классов с использованием ключевого слова «const«. Определение констант в глобальной области видимости с помощью «define» допустимо, но не рекомендуется.

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

Строки

Строковые литералы

Когда строка является литеральной (не содержит подстановок переменных), для ее обрамления должны использоваться апострофы или «одинарные кавычки«:

  1. $a = 'Example String';

Строковые литералы, содержащие апострофы

Когда строка литералов сама содержит апострофы, разрешается для обрамления строки использовать «двойные кавычки«. Это особенно актуально для SQL-запросов:

  1. $sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";

Синтаксис выше является более предпочтительным, чем экранирование апострофов.

Подстановка переменных

Подстановка переменных предпочтительнее с использование конкатенации строк, но разрешается с использованием нижеприведенной формы:

  1. $greeting = "Hello {$name}, welcome back!";

Для надежности, эта форма не допустима:

  1. $greeting = "Hello ${name}, welcome back!";

Конкатенация строк

Строки должны объединятся с помощью оператора «.«. Пробел должен всегда добавляться до и после оператора «.» для улучшения читабельности:

  1. $company = 'Vse' . 'Instrumenti';

Когда производится конкатенация строк с помощью оператора «.«, разрешается разрывать выражение на несколько строк для улучшения читабельности. В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы оператор «.» был выровнен под оператором «=«:

  1. $sql = "SELECT `id`, `name` FROM `people` "
  2.      . "WHERE `name` = 'Susan' "
  3.      . "ORDER BY `name` ASC";

Массивы

Массивы с числовыми индексами

Отрицательные числа в качестве индексов запрещены. Хотя индекс массива может начинаться с отрицательного числа, но это не приветствуется и рекомендуется, чтобы все массивы начинали индексирование с 0.

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

  1. $sampleArray = array(1, 2, 3, 'Vse', 'Instrumenti');

Также разрешается определять многострочные индексированные массивы, используя конструкцию «array«. В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы начало каждой строки было выровнено, как показано ниже:

  1. $sampleArray = array(1, 2, 3, 'Vse', 'Instrumenti',
  2.                      $a, $b, $c,
  3.                      56.44, $d, 500);

Ассоциативные массивы

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

  1. $sampleArray = array('firstKey'  => 'firstValue',
  2.                      'secondKey' => 'secondValue');

Классы

Определение класса

Классы должны определяться по следующей схеме.

Фигурная скобка всегда пишется на той же строке где и имя класса.

Код внутри класса должен иметь отступ в два пробела.

Класс должен быть логически разделен на блоки. Ниже приведен список возможных блоков, а также их порядок следования в объявлении класса:

  1. Константы;
  2. Переменные;
  3. Методы.

Каждый блок должен начинаться с пустой строки и комментария с названием блока. Объявлять блок не надо, если соответствующие элементы класса отсутствуют.

Методы класса, как магические, так и обычные, должны быть разделены между собой комментарием в виде разделительной черты.

Ниже приведен пример объявления класса с блоками и разделительной чертой между методами:

  1. /**
  2.  * Doc-блок здесь
  3.  */
  4. class SampleClass {
  5. 
    
  6.   //============================================================================
  7.   // Константы
  8.   //============================================================================
  9.   /**
  10.    * Doc-блок здесь
  11.    */
  12.   const CUR_SITE = 1;
  13. 
    
  14.   //============================================================================
  15.   // Переменные
  16.   //============================================================================
  17.   /**
  18.    * Doc-блок здесь
  19.    */
  20.   static public $vseInsDbPointer;
  21.   /**
  22.    * Doc-блок здесь
  23.    */
  24.   static public $root = '';
  25. 
    
  26.   //============================================================================
  27.   // Методы
  28.   //============================================================================
  29.   /**
  30.    * Doc-блок здесь
  31.    */
  32.   static public function connectVseInsDb() {
  33.     // Подключение к базе данных
  34.     self::$vseInsDbPointer = mysql_connect(self::DB_VSEINS_HOST,
  35.                                            self::DB_VSEINS_USER,
  36.                                            self::DB_VSEINS_PASS)
  37.     or die('VseInstrumenti.Ru: could not connect database - ' . mysql_error());
  38.     mysql_select_db(self::DB_VSEINS_NAME, self::$vseInsDbPointer);
  39.     // Установим кодировку
  40.     mysql_query('SET NAMES cp1251', self::$vseInsDbPointer);
  41.   }
  42.   //----------------------------------------------------------------------------
  43.   /**
  44.    * Doc-блок здесь
  45.    */
  46.   static public function disconnectVseInsDb() {
  47.     mysql_close(self::$vseInsDbPointer);
  48.   }
  49. }

Только один класс разрешен внутри одного PHP-файла.

Размещение дополнительно кода в файле с классом разрешено, но не приветствуется. В таких файлах, две пустые строки должны разделять класс и дополнительный PHP-код.

Переменные-члены классов

Переменные-члены классов должны определяться по следующей схеме.

Ключевое слово «var» не разрешено. Члены класса должны всегда определять их область видимости, используя ключевое слово «private«, «protected» или «public«. Доступ к переменным-членам класса напрямую используя префикс «public» разрешено, но не приветствуется в пользу методов доступа (set/get).

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

Определение функций и методов

Функции должны определяться по следующей схеме.

Функции внутри классов должны всегда определять свою область видимости с помощью одного из префиксов «private«, «protected» или «public«.

Как и у классов, фигурная скобка всегда пишется на той же строке где и имя функции. Пробелы между именем функции и круглой скобкой для аргументов отсутствуют.

Функции в глобальной области видимости крайне не приветствуются.

Это пример допустимого определения функции:

  1. /**
  2.  * Doc-блок здесь
  3.  */
  4. class Foo {
  5. 
    
  6.   //============================================================================
  7.   // Методы
  8.   //============================================================================
  9.   /**
  10.    * Doc-блок здесь
  11.    */
  12.   public function bar() {
  13.     // содержимое класса должно быть
  14.     // с отступом в два пробела
  15.   }
  16. 
    
  17. }

ЗАМЕЧАНИЕ: Передача по ссылке допустима только в определениях функций:

  1. /**
  2.  * Doc-блок здесь
  3.  */
  4. class Foo {
  5. 
    
  6.   //============================================================================
  7.   // Методы
  8.   //============================================================================
  9.   /**
  10.    * Doc-блок здесь
  11.    */
  12.   public function bar(&$baz) {
  13.   }
  14. 
    
  15. }

Передача по ссылке во время вызова запрещена.

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

  1. /**
  2.  * Doc-блок здесь
  3.  */
  4. class Foo {
  5. 
    
  6.   //============================================================================
  7.   // Методы
  8.   //============================================================================
  9.   /**
  10.    * ПЛОХО
  11.    */
  12.   public function bar() {
  13.     return($this->bar);
  14.   }
  15.   //----------------------------------------------------------------------------
  16.   /**
  17.    * ХОРОШО
  18.    */
  19.   public function bar() {
  20.     return $this->bar;
  21.   }
  22. 
    
  23. }

Использование функций и методов

Аргументы функции разделяются одним завершающим пробелом после каждой запятой. Это пример допустимого вызова функции для функции, которая принимает три аргумента:

  1. threeArguments(1, 2, 3);

Передача по ссылке во время вызова запрещена. Смотрите секцию определения функций для правильного способа передачи аргументов функции по ссылке. Для функций, чьи аргументы допускают массив, вызов функции может включать конструкцию «array» и может быть разделено на несколько строк для улучшения читабельности. В этом случае, применим стандарт описания массивов:

  1. threeArguments(array(1, 2, 3), 2, 3);
  2. 
    
  3. threeArguments(array(1, 2, 3, 'Vse', 'Instrumenti',
  4.                      $a, $b, $c,
  5.                      56.44, $d, 500), 2, 3);

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

if / else / elseif

Управляющие структуры, основанные на конструкциях «if» и «elseif«, должны иметь один пробел до открывающей круглой скобки условия, и один пробел после закрывающей круглой скобки.

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

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

  1. if ($a != 2) {
  2.   $a = 2;
  3. }

Для выражения «if«, включая «elseif» или «else«, форматирование должно быть таким, как в следующем примере:

  1. if ($a != 2) {
  2.   $a = 2;
  3. } else {
  4.   $a = 7;
  5. }
  6. 
    
  7. if ($a != 2) {
  8.   $a = 2;
  9. } elseif ($a == 3) {
  10.   $a = 4;
  11. } else {
  12.   $a = 7;
  13. }

PHP допускает написание таких выражений без фигурных скобок при некоторых условиях. Стандарт кодирования не делает различий — для всех «if«, «elseif» или «else» выражений необходимо использовать фигурные скобки.

Использование «elseif» конструкции допускается, но крайне не приветствуется в пользу «else if» комбинации.

switch

Управляющие структуры, написанные с использованием «switch» конструкции, должны иметь один пробел до открывающей круглой скобки условного выражения, и также один пробел после закрывающей круглой скобки.

Открывающаяся фигурная скобка пишется на той же строке, где и конструкция «switch«. Закрывающаяся фигурная скобка пишется на отдельной строке. Все содержимое между фигурными скобками пишется с отступом в два пробела. Содержимое каждого «case» выражения должно писаться с отступом в дополнительные два пробела.

  1. switch ($numPeople) {
  2.   case/span> 1:
  3.     break;
  4. 
    
  5.   case 2:
  6.     break;
  7. 
    
  8.   default:
  9.     break;
  10. }

ЗАМЕЧАНИЕ: Иногда полезно писать «case» выражения, которые передают управление следующему «case» выражению, опуская «break» или «return«. Для того, чтобы отличать такие случаи от ошибок, каждое «case» выражение, где опущен «break» или «return«, должно содержать комментарий «// break опущен специально«.

for / foreach

Управляющие структуры, написанные с использованием «for» / «foreach» конструкции, должны иметь один пробел до открывающей круглой скобки с выражением, и также один пробел после закрывающей круглой скобки.

Открывающаяся фигурная скобка пишется на той же строке, где и конструкция «for» / «foreach«. Закрывающаяся фигурная скобка пишется на отдельной строке. Все содержимое между фигурными скобками пишется с отступом в два пробела.

  1. for ($i = 0; $i < 10; $i++) {
  2.   ++$a;
  3. }
  4. 
    
  5. 
    
  6. foreach ($arr as $key => $value) {
  7.   ++$a;
  8. }

PHP допускает написание таких выражений без фигурных скобок при некоторых условиях. Стандарт кодирования не делает различий — для всех «for» или «foreach» выражений необходимо использовать фигурные скобки.

while

К написанию управляющих структур «while» предъявляются те же требования, как и к конструкциям описанным выше.

  1. while ($a < 10) {
  2.   ++$a;
  3. }

Встроенная документация

Формат документации

Все блоки документации («doc-блоки«) должны быть совместимы с форматом phpDocumentor. Описание формата phpDocumentor вне рамок данного документа.

Все файлы с исходными кодами, написанные в нашей организации, должны содержать «файловые» doc-блоки в начале каждого файла и «классовый» doc-блок непосредственно перед каждым классом. Ниже даны примеры таких doc-блоков.

Файлы

Каждый файл, содержащий PHP-код должен иметь заголовочный блок в начале файла, содержащий как минимум следующие phpDocumentor-теги:

  1. /**
  2.  * Краткое описание файла
  3.  *
  4.  * Длинное описание файла (если есть)...
  5.  *
  6.  */

Классы

Каждый класс должен иметь doc-блок, содержащий как минимум следующие phpDocumentor-теги:

  1. /**
  2.  * Краткое описание класса
  3.  *
  4.  * Длинное описание класса (если есть)...
  5.  *
  6.  * @author FirumyanAK
  7.  */

Также рекомендуется наличие phpDocumentor-тега «@version«:

@version 1.0.1.25

Функции

Каждая функция, включая методы объектов, должна иметь doc-блок, содержащий как минимум:

  • описание функции;
  • все аргументы;
  • все возможные возвращаемые значения.

Нет надобности использовать тег «@access«, потому что область видимости уже известна из ключевых слов «public«, «private» или «protected«, используемых при определении функции.

Ниже приведен пример doc-блока функции:

  1. /**
  2.  * Функция, которая возвращает цену товара для оптовика указанного типа
  3.  * @param double $retailPrice розничная цена товара
  4.  * @param double $purchasingPrice закупочная цена товара
  5.  * @param string $status статус оптовика
  6.  * @return double цена товара
  7.  */

Константы

Каждая константа должна иметь doc-блок, содержащий как минимум:

  • описание константы;
  • тип константы.

Ниже приведен пример doc-блока:

  1. /**
  2.  * Идентификатор текущего сайта
  3.  * @var int
  4.  */

Переменные

Рекомендуется, чтобы переменные-члены класса, также имели doc-блок, но это требование не является обязательным. Если doc-блок имеется, то он должен содержать как минимум: описание переменной; тип переменной.

Ниже приведен пример doc-блока:

  1. /**
  2.  * Указатель на соединение с базой VseInstrumenti.Ru
  3.  * @var resource
  4.  */

Ссылки

  1. За основу взять стандарт кодирования на PHP в Zend Framework’е – http://framework.zend.com/manual/ru/coding-standard.html.
  2. Также использовался материал система документирования исходных текстов на PHP phpDocumentor – http://phpdoc.org/.

Источник: yapro.ru

Оставить комментарий

Чтобы оставлять комментарии Вы должны быть авторизованы.

Похожие посты