Новости из Блогов Kohana: Правила и стили написания кода (PHP)

Kohana: Правила и стили написания кода (PHP)

Вольный перевод статьи Kohana: Conventions and Coding Style.
С стилем согласен, до чего-то из этого доходил сам, но тут все систематизировано и разложено по полочкам. Примеры кода, написанного в таком стиле можно посмотреть на гитхабе.

Правила и стили написания кода

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


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

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

Соблюдайте следующие условия:
Нельзя использовать CamelCase в именах классов, кроме случаев, когда нежелательно создание нового уровня каталогов.
Все имена файлов и папок должны быть в нижнем регистре.
Все классы должны располагаться в папке classes . Папка может быть на любом уровне каскадной файловой системы.

В отличие от Kohana 2.x, сейчас нет разделения между «контроллерами», «моделями», «библиотеками» и «хелперами». Все классы должны располагаться в папке «classes/», независимо от того, являются ли они статическими «хелперами» или «библиотеками». Вы можете использовать любые паттерны, например singleton, adapter и др.

Примеры

Помните, что подчеркивание в имени файла означает новый каталог. Рассмотрим следующие примеры:
Имя класса Путь к файлу
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 Style при использовании скобок. Скобки всегда должны находиться на своей линии. Исключение составляют только открывающая скобка в классах, которая может быть на одной линии.

Code:

if ($foo == 'bar')
{
    $baz->bar();
}
else
{
    $baz->default();
}
 
// Открывающая класс скобка может быть на той же линии
class Foobar {

Правила наименования

Kohana использует наименование_с_подчеркиванием, а не camelCase.
Классы

Code:

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

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

Code:

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

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

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

Code:

function drink_beverage($beverage)
{

Переменные

Все переменные должны быть в нижнем регистре и использовать нижние_подчеркивания, а не camelCase.

Code:

// Правильно:
$foo = 'bar';
$long_example = 'использовать подчеркивание';
 
// Неправильно:
$weDontWantThis = 'понятно?';

Отступы

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

Code:

$text = 'Это длинный блок текста, который будет перенесен. Обычно перенос '
      .'осуществляется на 80 символе. Отступы очень важны для повышения '
      .'читаемости кода. Запомните, что все отступы должны быть с помощью '
      .'tab\'ов, но вертикальные отступы должны быть с использованием'
      .'пробелов, вместо tab\'ов.';

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

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

Code:

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

Однострочные конструкции

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

Code:

/ Приемлемо:
if ($foo == $bar)
    return $foo;
 
if ($foo == $bar)
    continue;
 
if ($foo == $bar)
    break;
 
if ($foo == $bar)
    throw new Exception('Вы все испортили!');
 
// Неприемлемо:
if ($baz == $bun)
    $baz = $bar + 2;

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

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

Code:

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

Пожалуйста, используйте elseif, а не else if:

Code:

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

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

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

Code:

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

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

После if должен быть пробел, а затем идти скобка. Символ «!» должен иметь пробел с каждой стороны для максимальной читаемости кода. За исключением «!» или приведения типа, перед закрывающей и открывающей скобкой не должно быть пробелов.

Code:

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

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

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

Code:

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

Все сравнения и выражения должны быть внутри скобок:

Code:

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

При разделении комплекса тернарных выражений (выражений, первая часть которых больше ~80 символов) на несколько строк, для выделения операторов должны использоваться пробелы, которые должны идти перед строкой с выражением.

Code:

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

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

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

Code:

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

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

Code:

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

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

Code:

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

Константы

Всегда используйте верхний регистр для констант:

Code:

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

Размещайте сравнение с константой в конец выражения:

Code:

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

Это несколько спорно, поэтому я объясню причины. Если прочитать предыдущее выражение на человеческом языке, в правильном примере это будет звучать так:
Если переменная $foo точно не равна FALSE

А некорректный пример так:

Code:

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

Поскольку мы читаем слева направо, то просто не имеет смысла ставить константу первой.

Комментарии

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

Code:

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

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

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

Code:

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

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

Code:

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

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

Code:

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

Наконец, имейте ввиду, что использование символа $ для конца строки разрешает использование символа новой строки. Используйте модификатор D для исправления этого, если необходимо. Подробнее.

Code:

$str = "[email protected]<script type="text/javascript">
/* <![CDATA[ */
(function(){try{var s,a,i,j,r,c,l=document.getElementById("__cf_email__");a=l.className;if(a){s='';r=parseInt(a.substr(0,2),16);for(j=2;a.length-j;j+=2){c=parseInt(a.substr(j,2),16)^r;s+=String.fromCharCode(c);}s=document.createTextNode(s);l.parentNode.replaceChild(s,l);}}catch(e){}})();
/* ]]> */
</script>\n";
 
preg_match('/^.+@.+$/', $str);  // TRUE
preg_match('/^.+@.+$/D', $str); // FALSE

1/12/2012
http://bafoed.net/post/13472/

 

Использую всё так, кроме
AND, OR (использую &&, ||) и
($foo !== FALSE) - пишу (FALSE !== $foo)

 

По большому счету бред. Польза от данных рекомендаций стремится к нулю. Всегда пиши так как более просто и понятно, не нужно выдумывать.
ЗЫ по поводу eregi вообще долго смеялся, последний раз видел реализацию в проекте, во время PHP 4