Education:Standards

Материал из phpXCoreWiki.

(Перенаправлено с Standards)
Перейти к: навигация, поиск

Содержание

[править] Стандарты кодирования PHP

Что нагуглил:

Теперь надо смержить...

[править] Отступы

спользуйте для отступа 4 пробела, а не табуляцию.

[править] Управляющие структуры

Управляющие структуры включают в себя операторы if, for, while, switch, и др. Ниже приведен пример оформления оператора if, который в этом отношении является самым сложным:

if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}

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

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


if (true) {
    echo 'always true';
} else {
    echo 'never';
}


Пример синтаксиса оператора switch:

switch (condition) {
case 1:
    action1;
    break;
 
case 2:
    action2;
    break;
 
default:
    defaultaction;
    break;
 
}

[править] Вызовы функций

Вызовы функций должны быть написаны без отступов между именем функции, открывающей скобкой и первым параметром. Отступы в виде пробела должны присутствовать после каждой запятой в перечислении параметров. Пробелов также не должно быть между последним параметром, закрывающей скобкой и точкой с запятой. Пример:

$var = foo($bar, $baz, $quux);

Как можно заметить, в примере используются пробелы с двух сторон от знака "=". Если подобные присвоения результатов функций переменным объединяются в блоки, то для повышения читабельности рекомендуется следующий синтаксис:

$short         = foo($bar);
$long_variable = foo($baz);


[править] Определения функций

Определения функций следуют такому cоглашению:

/**
 * fooFunction
 *
 * description foo function
 *
 * @access  public
 * @param   integer $arg1  integer data
 * @param   string  $arg2  some string
 * @return  string
 */
function fooFunction($arg1, $arg2 = '')
{
    if ($arg2) {
        $val = $arg2;
    } else {
        $val = $arg1;
    }
    return $val;
}

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

Аргументы функций со значениями по умолчанию должны находиться в конце списка аргументов. Функции всегда должны возвращать значение, если это возможно в принципе. Чуть более подробный пример:

/**
 * parseDSN
 *
 * wraper for function DB::parseDSN
 *
 * @access  public
 * @param   mixed $dsn string or array
 * @return  array $dsninfo
 */
function parseDSN($dsn)
{
    if (is_array($dsn)) {
        $dsninfo = $dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }
 
    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }
 
    return $dsninfo;
}

[править] Комментарии

Комментарии внутри кода классов должны соответствовать синтаксису комментариев PHPDoc, который напоминает Javadoc. За дополнительной информацией о PHPDoc обращайтесь сюда: http://www.phpdoc.org/

Дополнительные комментарии, кроме тех, что предусмотрены PHPDoc, только приветствуются. Основное правило в данном случае - каждая часть кода повышенной сложности должна быть прокомментирована до того, как вы забыли как она работает.

Подходят комментарии в стилях C (/* */) и C++ (//). спользование комментариев в стиле Perl/shell (#) не рекомендуется.

[править] Подключение кода (including)

В тех местах, где вы используете подключение файлов других классов вне зависимости от условий, используйте конструкцию require_once(). Если же подключение файлов зависит от каких-либо условий, то следует использовать include_once(). В этом случае вы всегда будете уверены в том, что файлы подключаются только единожды.

Примечание: include_once() и require_once() и являются конструкциями, а не функциями. Вам не обязательно использовать скобки вокруг имени файла, который подключается.

[править] Тэги PHP-кода

Всегда используйте <?php ?> вместо <? ?>для выделения PHP-кода. Это необходимо для обеспечения работы приложений на разных операционных системах и с различными настройками.


[править] Соглашения об именах

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

[править] Переменные

Под переменными понимаются служебные переменные, определённые в методах или функциях. Применение префиксов не приветствуется, кроме как в случаях, требующих разрешения неоднозначности. Массивы следует именовать, подчеркивая множественную природу содержимого.

Примеры:

 $Counter - целочисленный счётчик;
 $objCounter - экземпляр класса "счётчик";
 $Usd2Uah - курс бакса к гривне, double;
 $CurrencyRates - массив курсов (скорее всего ассоциативный);


Переменные циклов, переменные для хранения временных значений и приравненные к ним:

 $i, $j, $k, $l, $tmp, $temp_val и т.д.

[править] Классы

При именовании класса использовать 1-3 слова - существительные с необязательными прилагательными (если не хватает 3-х слов, то есть вероятность, что вы пытаетесть 1 класс заставить делать больше, чем он должен). Слова разделяются ЗАГЛАВНЫМ буквами. Пример:

 class User
 class UserRegistration
 class DataGrid

[править] Методы

Методы именовать так же как и классы, за исключением того, что имя метода дожно начинаться с глагола. Обычно - set, get, is. Пример:

public SetCurrentRate($aNewRate );
  public IsValid($aUser2Check );

[править] Свойства

Свойства именовать как Переменные (1.1)

[править] Приватные методы\свойства

меновать как методы\свойства, но имя начинать с _ (подчерка) Пример:

function _SecretMethod();
  var $_Variable4InternalUsage;

[править] Параметры методов\функций

меновать как классы, с префиксом "a" Пример:

function setCurrentDate($aNewDate) {
    global $global_var;
    $Var = 34;
    ...
  }

[править] Глобальные функции\переменные

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

 $current_rate_position
 function copy_users ( aFrom, aTo )

[править] Константы

мена констант всегда должны быть в верхнем регистре с подчеркиваниями для разделения слов. В качестве префикса в именах констант должно использоваться имя пакета/класса, в котором они используются. Например, все константы, которые используются в пакете DB::, начинаются с "DB_".

define('DB_USER', 'user');
define('DB_PASS', 'pass');

[править] Ключи массивов

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

$Value1 = $SomeArr['key1'];

збегать обращений к элементам массива внутри строк. То есть

$Value1 = "Value of $key1's element is {$SomeArr['key1']}.";

хуже чем

$Value1 = 'Value of ' . $key1 . '\'s element is ' . $arrSomeArr['key1'] . '.';

[править] Форматированные строки

Должны записываться с отступом и с сохранением исходного форматирования.

$user_query = "
		SELECT 
			emp_id,
			emp_name,
			emp_email
		FROM
			employee
		WHERE
			emp_id IN (23, 45) AND
			emp_name LIKE '%vasya%'
	";

[править] Библиотека классов

Базируется на Zend Coding Standart

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

  • Database
  • FileSystem

мя главного класса должно совпадать с именем пакета:

  • Database
  • FileSystem

Все второстепенные классы должны содержать в своём имени префикс составленный из имени пакета:

  • Database_Driver
  • FileSystem_Manager

Все наследуеммые классы в данном пакете должны содержать префикс состоящий из имени предка:

  • Database_Driver_MySQL
  • FileSystem_Manager_CSV

мя файла содержащего класс должен совпадать с именем класса и содержать постфикс ".class":

  • Database.class.php
  • FileSystem.class.php

мя дериктории пакета должно состоять из имени пакета

  • Example
  • Database
  • FileSystem

Все наследуемые классы (от основного или второстепенных классов) должны лежать в папках названных в соответствии с именем предка:

  • Database\Driver\MySQL.class.php
Личные инструменты