K4:Стиль программирования

From In-Portal Developers Guide

Path to article:

Сообщество > Документация > Дополнения > Стандарты в программировании

(Difference between revisions)

Jump to: navigation, search

You need to have JavaScript enabled to use this page.

Current revision

Стандарты в программировании

Статьи в этой категории

1 Выделение PHP кода
2 Строки
3 Массивы
- 3.1 Массивы с числовыми ключами
- 3.2 Ассоциативные массивы
4 Классы
- 4.1 Объявление классов
- 4.2 Атрибуты класса
5 Функции и методы
- 5.1 Объявление функций и методов
- 5.2 Использование функций и методов
6 Управляющие структуры
- 6.1 If / Else / Elseif
- 6.2 Switch

Выделение PHP кода

PHP код должен быть всегда заключён в стандартные тэги в полной форме:

<?php

?>

Тэги в короткой форме запрещены. Для файлов, содержащих только PHP код писать закрывающий тэг не нужно (см. Общее).

Строки

Символьные строки

Если строка символьная (не содержит в себе подстановок переменных), то её нужно заключать в апострофы или "одинарные кавычки":

$a = 'Example String';

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

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

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

Лучше использовать выше приведённый синтаксис, нежели экранировать апострофы в строке.

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

Подстановка переменных разрешается только двумя ниже приведёнными способами:

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

Из соображений целостности запрещается использовать следующий способ:

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

Объединение строк

Строки можно объединять используя оператор конкатенации ("."). Также, для улучшения читабельности, нужно ставить по пробелу до и после точки:

$company = 'Zend' . ' ' . 'Technologies';

При использовании оператора конкатенации разрешается разбивать строковое выражение на несколько строк:

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

Массивы

Массивы с числовыми ключами

Отрицательные числа использовать в качестве ключей нельзя. Ключи массива должны начинаться с любого положительного числа, но всё же рекомендуется начинать массив с нуля. Если массив объявляется используя ключевое слово "Array", то, для улучшения читабельности, нужно ставить по одному пробелу после каждой запятой и после самого ключевого слова "Array":

$sample_array = Array (1, 2, 3, 'Zend', 'Studio');

Также, при использовании ключевого слова "Array" разрешается объявлять массив на нескольких строках. В таком случае каждая стока должна быть сдвинута (padded) одним табулятором:

$sample_array = Array (
	1, 2, 3, 'Zend', 'Studio',
	$a, $b, $c,
	56.44, $d, 500
);

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

При объявлении большого (больше 5 ключей) ассоциативного массива с использованием ключевого слова "Array" его нужно разбивать на несколько строк. В таком случае можно (но не обязательно) при помощи пробелов выровнять массив так, чтобы разделители ключей и значений ("=>") были на одном уровне:

$sample_array = Array (
	'firstKey'  => 'firstValue',
	'secondKey' => 'secondValue'
);

Если всё таки выравнивать массив при помощи пробелов, то это нужно делать только на конечных массивах (в случае, когда несколько массивов вложены друг в друга).

Классы

Объявление классов

Классы должны называться согласно назначению имён.

Открывающаяся фигурная скобка всегда должна находиться на строке с названием класса. Между названием класса и открывающей фугурной скобкой должен стоять один пробел. Каждый класс должен иметь блок с документацией совместимый со стандартом PHPDocumentor. Любой код внутри класса должен быть выровнен при помощи одного табулятора (по одному на строку). В одном PHP файле разрешается объявлять только один класс. Размещать дополнительный код в файле с объявлением класса можно, но не рекомендуется. В таком случае нужно разделять любой дополнительный PHP код от объявления класса двумя пустыми строками. Ниже приведён пример допустимого объявления класса:

/**
 * Documentation Block Here
 */
class SampleClass {
	// entire content of class
	// must be indented one tab
}

Атрибуты класса

Атрибуты классов должны называться согласно назначению имён. Объявление атрибутов класса должно находиться в верху класса до объявления методов класса. В PHP4 нужно использовать ключевое слово "var" для объявления атрибутов класса. В PHP5 нужно использовать ключевые слова "private", "protected", или "public" для объявления атрибутов класса с указанием их видимости. Обращаться к атрибутам класса объявляя их с ключевым словом "public" можно, но не рекомендуется. В таком случае лучше использовать методы доступа (set/get).

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

Объявление функций и методов

Функции должны называться согласно назначению имён. В методах классов всегда должна быть указана их область видимости при помощи ключевых слов "private", "protected", или "public" (только для PHP5). Открывающаяся фигурная скобка всегда должна находиться на следующей строке после названия функции, также как и у классов. Между названием функции и открывающейся скобкой пробела ставить не нужно. Объявлять функции в глобальной области видимости не рекомендуется. Ниже приведён пример допустимого объявления метода класса:

/**
 * Documentation Block Here
 */
class Foo {
	/**
	 * Documentation Block Here
	*/
	public function bar()
	{
		// entire content of function
		// must be indented one tab
	}
}

Передача аргументов по ссылке разрешается только в объявлении функции:

/**
 * Documentation Block Here
 */
class Foo {
	/**
	 * Documentation Block Here
	*/
	public function bar(&$baz)
	{
		// entire content of function
		// must be indented one tab
	}
}

Передача аргументов в функцию по ссылке запрещена:

$variable = 'sample value';
Foo::bar(&$variable);

Передача тела sql запроса в функцию напрямую и без временной переменной запрещена, т.к. это ухудшает наглядность:

// WRONG
$installed = $this->Conn->GetOne('SELECT VariableValue FROM '.TABLE_PREFIX.'ConfigurationValues WHERE VariableName = \'InstallFinished\'');
 
// RIGHT
$sql = 'SELECT VariableValue
	FROM '.TABLE_PREFIX.'ConfigurationValues
	WHERE VariableName = "InstallFinished"';
$installed = $this->Conn->GetOne($sql);

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

/**
 * Documentation Block Here
 */
class Foo {
	/**
	 * WRONG
	*/
	public function bar()
	{
		return($this->bar);
	}
 
	/**
	 * RIGHT
	*/
	public function bar()
	{
		return $this->bar;
	}
}

Главные функции (методы) должны быть объявлены раньше подчинённых функций (методов):

/**
 * Documentation Block Here
 */
class Foo {
	/**
	 * main method
	*/
	public function mainMethod($value)
	{
		return $this->subMethod($value) + 15;
	}
 
	/**
	 * sub method
	*/
	public function subMethod($value)
	{
		return $value * 5;
	}
}

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

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

threeArguments(1, 2, 3);

Передача аргументов по ссылке запрещена. Для правильного использования функций следует предварительно ознакомиться с их объявлением. В случае, если в функцию можно передавать массивы, то разрешается использовать ключевое слово "Array" и разбивать вызов функции на несколько строк для улучшения читабельности. В таком случае стандарты объявления массивов остаются в силе:

threeArguments(Array(1, 2, 3), 2, 3);
 
threeArguments(
	Array (
		1, 2, 3, 'Zend', 'Studio',
		$a, $b, $c,
		56.44, $d, 500
	),
	2, 3
);

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

If / Else / Elseif

При использовании управляющих структур на основе ключевых слов if и elseif нужно ставить по одному пробелу до открывающей и после закрывающей скобки. Для улучшения читабельности нужно ставить пробелы вокруг каждого оператора в условии. Для логической группировки больших условий нужно использовать дополнительные скобки. Открывающая фигурная скобка ставиться на той же строке, что и условное выражение. Закрывающая фигурная скобка всегда ставиться на новой строке. Любой код между этими фигурными скобками должен быть сдвинут используя один табулятор.

if ($a != 2) {
	$a = 2;
}

В случае если вместе с ключевым словом "if" также используется слово "elseif" или "else", то код надо форматировать так, как показано в следующих примерах:

if ($a != 2) {
	$a = 2;
}
else {
	$a = 7;
}
 
 
if ($a != 2) {
	$a = 2;
}
elseif ($a == 3) {
	$a = 4;
}
else {
	$a = 7;
}

PHP разрешает не ставить фигурные скобки в некоторых случаях. Не смотря на это надо следовать стандартам программирования и всегда использовать фигурные скобки при работе с ключевыми словами "if", "elseif" или "else". Использовать ключевое слово "elseif" можно, но всё же рекомендуется вместо него использовать "else if" комбинацию.

Switch

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

switch ($numPeople) {
	case 1:
		$sample_code = 'test';
		break;
 
	case 2:
		break;
 
	default:
		break;
}

Нужно всегда указывать ключевое слово "default". В некоторых случаях бывает удобнее не писать ключевое слово "break". В таком случае вместо "break" нужно писать комментарий "// break intentionally omitted", чтобы отсутствие "break" не было расценено как ошибка.

In-Portal Developers Guide