15 KiB
Соглашения
При работе с фреймворком приветствуется использование Kohana coding style. В нем используется BSD/Allman стиль расстановки фигурных скобок и прочего форматирования кода.
Имена классов и расположение файлов
Для облегчения работы автозагрузки в Kohana, имена классов строго регламентированы. Имя класса должно начинаться с заглавной буквы, а для разделения слов в имени используется нижнее_подчёркивание. Нижнее подчёркивание отражает расположение файла в файловой структуре проекта.
Данные соглашения предусматривают:
- Не рекомендуется использовать CamelCase в имени класса, за исключением случаев, когда нежелательно создавать дополнительные поддиректории.
- Все файлы классов и директории должны быть в нижнем регистре.
- Все классы должны располагаться в директории
classes, которая может быть на любом уровне каскадной файловой системы фреймворка.
[!!] В отличие от 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 |
Стандарты кодирования
Для того, чтобы Ваш код был удобочитаемым и выглядел последовательным, мы просим всех на максимально придерживаться стандартов кодирования.
Фигурные скобки
Используйте, пожалуйста, BSD/Allman стиль расстановки фигурных скобок.
Соглашение в именовании классов
В 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, чтобы этого избежать. Подробная информация.
$str = "email@example.com\n";
preg_match('/^.+@.+$/', $str); // TRUE
preg_match('/^.+@.+$/D', $str); // FALSE