# Соглашения

При работе с фреймворком приветствуется использование Kohana [coding style](http://dev.kohanaphp.com/wiki/kohana2/CodingStyle). В нем используется [BSD/Allman стиль](http://ru.wikipedia.org/wiki/%D0%9E%D1%82%D1%81%D1%82%D1%83%D0%BF_%28%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%29#.D0.A1.D1.82.D0.B8.D0.BB.D1.8C_.D0.9E.D0.BB.D0.BC.D0.B0.D0.BD.D0.B0) расстановки фигурных скобок и прочего форматирования кода.

## Имена классов и расположение файлов {#classes}

Для облегчения работы [автозагрузки](about.autoloading) в Kohana, имена классов строго регламентированы. Имя класса должно начинаться с заглавной буквы, а для разделения слов в имени используется нижнее_подчёркивание. Нижнее подчёркивание отражает расположение файла в файловой структуре проекта.

Данные соглашения предусматривают:

1. Не рекомендуется использовать CamelCase в имени класса, за исключением случаев, когда нежелательно создавать дополнительные поддиректории.
2. Все файлы классов и директории должны быть в нижнем регистре.
3. Все классы должны располагаться в директории `classes`, которая может быть на любом уровне [каскадной файловой системы](about.filesystem) фреймворка.

[!!] В отличие от Kohana версии 2.x, в Kohana 3 нет разделения между "типами" классов: будь то "контроллер", "модель", "библиотека" или "хелпер". Все классы располагаются в директории "classes/" вне зависимости от того, являются ли они статическими "хелперами" или объектами "библиотеки". Вы вправе реализовывать любой дизайн класса, который Вам необходим: статический, синглтон, адаптер и т.п.

## Примеры

Помните, нижнее подчёркивание в наименовании класса отвечает за разделение на директории и отражает расположение файла в файловой структуре проекта.

Название класса       | Файл
----------------------|-------------------------------
Controller_Template   | classes/controller/template.php
Model_User            | classes/model/user.php
Database              | classes/database.php
Database_Query        | classes/database/query.php
Form                  | classes/form.php

## Стандарты кодирования {#coding_standards}

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

### Фигурные скобки

Используйте, пожалуйста, [BSD/Allman стиль](http://ru.wikipedia.org/wiki/%D0%9E%D1%82%D1%81%D1%82%D1%83%D0%BF_%28%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%29#.D0.A1.D1.82.D0.B8.D0.BB.D1.8C_.D0.9E.D0.BB.D0.BC.D0.B0.D0.BD.D0.B0) расстановки фигурных скобок.

### Соглашение в именовании классов

В Kohana используется нижнее_подчёркивание в именовании классов. Именование с использованием camelCase не приветствуется.

#### Классы

	// Корневые библиотеки используют суффикс _Core
	class Beer_Core {

	// При расширение функционала библиотеки суффикс не используется
	class Beer extends Beer_Core

	// Класс контроллера использует суффикс _Controller
	class Apple_Controller extends Controller {

	// Класс модели использует суффикс _Model
	class Cheese_Model extends Model {

	// Класс хелпера
	class peanut {

Если Вы не передаёте параметры в конструктор при создании класса, не используйте круглые скобки при его объявлении:

	// Правильно:
	$db = new Database;

	// Не правильно:
	$db = new Database();

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

Имена функций должны быть в нижнем регистре и использовать нижнее_подчёркивание для разделения слов:

	function drink_beverage($beverage)
	{

#### Переменные

Все переменные должны быть в нижнем регистре и использовать нижнее_подчёркивание для разделения слов (camelCase использовать запрещено):

	// Правильно:
	$foo = 'bar';
	$long_example = 'uses underscores';

	// Не правильно:
	$weDontWantThis = 'understood?';

### Отступы

Используйте табуляцию для отступов в Вашем коде. Использование пробелов вместо табуляции строго запрещено.

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

	$text = 'это разделённый на несколько строк длинный текст. Зачастую, '
		  . 'при многострочном разделении используют ограничение в 80 знаков '
		  . 'на строку. Для удобочитаемости кода крайне важно применять правильное '
		  . 'вертикальное выравнивание текста. Помните, что любые отступы '
		  . 'должны выполняться в виде табуляции, а вертикальное выравнивание уже '
		  . 'должно завершаться пробелами, которые идут сразу после табов .';

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

Не используйте пробелы вокруг оператора конкатенации:

	// Правильно:
	$str = 'one'.$var.'two';

	// Не правильно:
	$str = 'one'. $var .'two';
	$str = 'one' . $var . 'two';

### Однострочные операторы

Однострочные операторы IF могут быть использованы лишь в случае прерывания выполнения кода (например, return или continue):

	// Допустимо:
	if ($foo == $bar)
		return $foo;

	if ($foo == $bar)
		continue;

	if ($foo == $bar)
		break;

	if ($foo == $bar)
		throw new Exception('You screwed up!');

	// Не допустимо:
	if ($baz == $bun)
		$baz = $bar + 2;

### Операторы сравнения

Используйте, пожалуйста, для сравнения операторы OR и AND:

	// Правильно:
	if (($foo AND $bar) OR ($b AND $c))

	// Не правильно:
	if (($foo && $bar) || ($b && $c))

Используйте, пожалуйста, elseif вместо else if:

	// Правильно:
	elseif ($bar)

	// Не правильно:
	else if($bar)

### Конструкции switch

Каждый оператор case, break и default должны располагаться на новой строке. Блок внутри case и default должны иметь отступ в 1 таб.

	switch ($var)
	{
		case 'bar':
		case 'foo':
			echo 'hello';
		break;
		case 1:
			echo 'one';
		break;
		default:
			echo 'bye';
		break;
	}

### Круглые скобки

Необходимо отделять имя оператора и следующие за ним скобки пробелом. Оператор ! (оператор отрицания, восклицательный знак) для удобочитаемости должен быть выделен пробелом с обеих сторон.

	// Правильно:
	if ($foo == $bar)
	if ( ! $foo)

	// Не правильно:
	if($foo == $bar)
	if(!$foo)
	if ((int) $foo)
	if ( $foo == $bar )
	if (! $foo)

### Тернарные операторы

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

	$foo = ($bar == $foo) ? $foo : $bar;
	$foo = $bar ? $foo : $bar;

Все сравнения и операции должны быть заключены в круглые скобки:

	$foo = ($bar > 5) ? ($bar + $foo) : strlen($bar);

При многострочном разделении тернарного комплекса (при очень длинных условиях, превышающих длину в 80 знаков), для вертикального выравнивания стоит использовать пробелы. Операторы при этом должны располагаться один под другим:

	$foo = ($bar == $foo)
		 ? $foo
		 : $bar;

### Приведение типов

При приведении типов, следует использовать пробелы вокруг оператора приведения:

	// Правильно:
	$foo = (string) $bar;
	if ( (string) $bar)

	// Не правильно:
	$foo = (string)$bar;

По возможности, используйте приведение типов вместо тернарных операторов:

	// Правильно:
	$foo = (bool) $bar;

	// Не правильно:
	$foo = ($bar == TRUE) ? TRUE : FALSE;

При приведение к числовому или булеву типам, используйте сокращённый формат:

	// Правильно:
	$foo = (int) $bar;
	$foo = (bool) $bar;

	// Не правильно:
	$foo = (integer) $bar;
	$foo = (boolean) $bar;

### Константы

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

	// Правильно:
	define('MY_CONSTANT', 'my_value');
	$a = TRUE;
	$b = NULL;

	// Не правильно:
	define('MyConstant', 'my_value');
	$a = True;
	$b = null;

При сравнении располагайте константы в конце:

	// Правильно:
	if ($foo !== FALSE)

	// Не правильно:
	if (FALSE !== $foo)

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

	если переменная $foo в точности не является FALSE

И для неверного:

	если FALSE в точности не является переменной $foo

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

### Комментарии

#### Однострочные комментарии

Используйте // перед строкой комментария, делайте отступ и начинайте комментарий с заглавной буквы. Никогда не используйте для комментариев #.

	// Правильно

	//Не правильно
	// не правильно
	# Не правильно

### Регулярные выражения

При использовании регулярных выражений, используйте синтаксис PCRE вместо POSIX. PCRE признан более мощной и быстрой библиотекой регулярных выражений.

	// Правильно:
	if (preg_match('/abc/i'), $str)

	// Не правильно:
	if (eregi('abc', $str))

Используйте одинарные кавычки вокруг регулярного выражения. Одинарные кавычки удобочитаемы ввиду их простоты. Строки, заключённые в одинарные кавычки, в отличие от двойных кавычек, не поддерживают интерполяцию переменных и конструкции с обратным слешем (\n, \t и т.д.).

	// Правильно:
	preg_match('/abc/', $str);

	// Не правильно:
	preg_match("/abc/", $str);

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

	// Правильно:
	preg_replace('/(\d+) dollar/', '$1 euro', $str);

	// Не правильно:
	preg_replace('/(\d+) dollar/', '\\1 euro', $str);

И в заключении, обратите внимание, что символ $ для определения позиции в конце строки не учитывает наличие символа новой строки.  Используйте при необходимости модификатор D, чтобы этого избежать. [Подробная информация](http://blog.php-security.org/archives/76-Holes-in-most-preg_match-filters.html).

	$str = "email@example.com\n";

	preg_match('/^.+@.+$/', $str);  // TRUE
	preg_match('/^.+@.+$/D', $str); // FALSE