Стиль кодирования

Комментарии: 8  Просмотры: 12 243

Старайтесь следовать единому стилю кодирования фреймворка Kohana. Это улучшает читабельность кода и позволяет с легкостью производить обмен кодом между разработчиками.

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

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

Применяются следующие правила:

1. Не должна использоваться так называемая Верблюжья нотация (напр. NewReport), кроме случаев, когда нежелательно создавать новый каталог.
2. Названия файлов с классами и директорий должны быть в нижнем регистре.
3. Все классы должны находиться в директории classes. Они могут находиться на любом уровне в каскадной файловой системе.

Примеры

Помните, что в классе подчеркивание означает новый каталог. Рассмотрим следующие примеры:

Class Name File Path
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 расстановку.

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

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

// Правильно
if ($a === $b)
{ 
    ... 
} 
else 
{ 
    ... 
} 
 
// Неправильно 
if ($a === $b) { 
    ... 
} else { 
    ... 
}

Скобки у класса

Единственное исключение — открывающая фигурная скобка класса. Она идет на той же линии.

// Правильно
class Foo { 
 
// Неправильно
class Foo
{

Пустые скобки

Не вставляйте никакие символы внутрь пустых скобок.

// Правильно
class Foo {}
 
// Неправильно
class Foo { }

Скобки у массивов

Массивы могут быть однострочные и многострочные

array('a' => 'b', 'c' => 'd')
 
array(    
     'a' => 'b',
     'c' => 'd',
)

Открывающая скобка

Открывающая скобка массива должна идти на той же линии

// Правильно
array(    
     ...
)
 
// Неправильно
array
(
    ...
)

Закрывающая скобка

Одномерный массив

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

// Правильно
$array = array(    
     ...
)
 
// Неправильно
$array = array(
    ...
    )

Многомерный массив

Правила те же, что и у одномерного, только у вложенного массива должен быть отступ на один TAB вправо.

// Правильно
array(
    'arr' => array(
        ...
    ),
    'arr' => array(
        ...
    ),
)
 
array(
    'arr' => array(...),
    'arr' => array(...),
)

Массивы, как аргументы функции

// Правильно
do(array(
    ...
))
 
// Неправильно
do(array(
    ...
    ))

Как отмечалось в начале раздела про массивы, однострочный стиль написания также вполне приемлем.

// Правильно
do(array(...))
 
// Альтернативный стиль написания, для разрыва длинных строк
do($bar, 'this is a very long line',
    array(...));

Правила написания имен

Kohana использует стандарт under_score (использование символа нижнего подчеркивания в качестве разделителя) и не использует camelCase (так называемую «Верблюжью нотацию») в названиях.

Классы

// Класс контроллера, использует префикс контроллера
class Controller_Apple extends Controller {
 
// Класс модели, использует префикс модели
class Model_Cheese extends Model {
 
// Обычный класс
class Peanut {

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

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

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

Функции должны быть в нижнем регистре и использовать подчеркивание для разделения слов.

function drink_beverage($beverage)
{

Переменные

Названия переменных должны быть в нижнем регистре и использовать подчеркивание, а не «верблюжью нотацию» для разделения.

// Правильно
$foo = 'bar';
$long_example = 'uses underscores';
 
// Неправильно
$weDontWantThis = 'understood?';

Отступ

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

$text = 'this is a long text block that is wrapped. Normally, we aim for '
      .'wrapping at 80 chars. Vertical alignment is very important for '
      .'code readability. Remember that all indentation is done with tabs,'
      .'but vertical alignment should be completed with spaces, after '
      .'indenting with tabs.';

Объединение строк (конкатенация)

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

// Правильно
$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 должен иметь отступ в одну табуляцию.

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


К записи оставлено 8 коммент.

А каковы правила использования закрывающего тега php «?>». Есть ли случаи когда его надо ставить в конце файла?

Не встречал, если честно. Только во вставках типа < ?php echo $name; ?> …..html-код.

На сколько видно по кодам в Kohana закрывающий тег «?>» не часто используется. Слышал, что это для ускорения обработчика PHP + вот ещё версия http://proger.net.ru/joomla/452

Есть много мнений, почему не стоит. Это и возможность попадания «лишних» символов и появление ошибки с заголовками. И возможность срабатывания вируса. У нас на одном из сайтов через фтп попала зараза и прописалась в конец всех php файлов сайта. Но так как закрывающий тег пхп отсутствовал, то интерпретатор php выдал ошибку и вредоносный код не сработал. А были бы теги, сработал бы.

Хм… для меня про код вируса самый весомый аргумент.

Обьясните пожалуйста для чего нужно файлы называть вот так Controller_Widget_Menu extends Controller_Template. В роутах ведь известно что открывать и где это искать! !!

По названию класса сразу видно, где его искать.
При чем тут роуты. А если мы класс наследуем ?

Controller_Widget_Menu зачем мне его так называть, его я не наследую и не собираюсь, согласен, что Controller_Template логично называть, чтоб знать где его искать. Так же интересно где создается обьект созданного класса контроллера мной, раз он работает, значить где-то создается обьект.



Оставить комментарий или два

Пожалуйста, зарегистрируйтесь для комментирования.