Education:Standards
Материал из phpXCoreWiki.
Содержание |
[править] Стандарты кодирования PHP
Что нагуглил:
- http://pear.php.net/manual/en/standards.php
- http://framework.zend.com/manual/en/coding-standard.html
- http://www.dagbladet.no/development/phpcodingstandard/
- http://www.evolt.org/article/PHP_coding_guidelines/18/60247/
- http://gforge.org/docman/view.php/1/2/coding-standards.html
- http://tony2001.phpclub.net/doc/standard/
Теперь надо смержить...
[править] Отступы
�спользуйте для отступа 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