301 lines
15 KiB
Markdown
301 lines
15 KiB
Markdown
# Соглашения
|
||
|
||
При работе с фреймворком приветствуется использование 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 |