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
|