Первая страница › Стандарты кодирования

Стандарты кодирования

Источник: 
Coding standards

Стандарты кодирования Drupal основаны на PEAR Coding standards. На drupal.org существует большее количество разделов по стандартам кодирования и они могут меняться, поэтому уточняйте текущие стандарты на drupal.org.

Отступы и пробелы

  • Отступы создаются двумя пробелами, табуляция не используется
  • В конце строк пробелы не используются
  • Для переноса строк используется запись \n (стандарт Unix, запись \r\n (стандарт Windows) не используется)
  • Все файлы должны заканчиваться пустой строкой (\n)
[к оглавлению]

Операторы

Все двоичные операторы — +, -, =, !=, ==, > и т.д. — должны отделяться от остального текста пробелом до и после оператора (для удобства чтения), например $foo = $bar;, а не $foo=$bar;. Единичные операторы — ++ — не отделяются пробелом от переменной или числа с которым они имеют дело.

[к оглавлению]

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

Используйте пробел между (типом) и $переменной: (int) $mynumber.

[к оглавлению]

Конструкции

Это правило включает использование if, for, while, switch и т.д.

Оператор должен отделять от круглой скобки один пробел — чтобы отличать операторы от функций. Мы настоятельно рекомендуем использовать фигурные скобки даже в ситуациях, когда их присутствие не является технически необходимым. Их наличие улучшает читаемость кода и уменьшает вероятность логических ошибок при добавлении новых строк.

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

Для конструкции switch следует использовать следующую запись:

switch (condition) {
  case 1:
    action1;
    break;

  case 2:
    action2;
    break;

  default:
    defaultaction;
    break;
}

а для do-while:

do {
  actions;
} while ($condition);

[к оглавлению]

Вызов функций

Пробел используется:

  • Между запятой и каждым параметром
  • С каждой стороны от знака равенства

Пробел не используется:

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

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

В случае, когда используется блок связанных команд, пробелы могут использоваться для их выравнивания — это улучшает чтение:

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

[к оглавлению]

Объявление функций

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

function funstuff_system($field) {
  $system["description"] = t("This module inserts funny text into posts randomly.");
  return $system[$field];
}

[к оглавлению]

Вызов классов

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

$foo = new MyClassName();

Это сохраняет последовательность с конструкциями имеющими аргументы:

$foo = new MyClassName($arg1, $arg2);

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

$bar = 'MyClassName';
$foo = new $bar();
$foo = new $bar($arg1, $arg2);

[к оглавлению]

Массивы

Массивы должны оформляться с использованием пробела между каждым элементом (после запятой) и оператором указания, — => — если он необходим (с двух сторон):

$some_array = array('hello', 'world', 'foo' => 'bar');

Отметьте: когда строка использует более 80 символов (обычный случай при кодировании форм и меню), каждый элемент следует располагать на новой строке с отступом в один уровень:

$form['title'] = array(
  '#type' => 'textfield',
  '#title' => t('Title'),
  '#size' => 60,
  '#maxlength' => 128,
  '#description' => t('The title of your node.'),
);

Отметьте: запятая в конце последнего элемента массива — это не опечатка! Это помогает предотвратить ошибки если другой элемент будет помещён в конец списка позже.

[к оглавлению]

Кавычки

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

Мы бы хотели только заметить здесь пару вещей. Как известно, строки с одинарными кавычками обрабатываются быстрее, т.к. обработчик не смотрит на используемые переменные. Поэтому рекомендуется их и использовать, но за исключением двух случаев:

  • Необходимо обработать переменные, например: <h2>$header</h2>
  • Одиночная кавычка используется в строке перевода. Например строка "He's a good person." в одиночных кавычках будет выглядеть как 'He\'s a good person.'. Такой вариант записи будет неправильно обработан генераторами .pot-файлов, кроме того, его и не слишком удобно читать
[к оглавлению]

Объединение строк

Всегда используйте пробел между точкой и объединяемой частью, для улучшения читаемости.

<?php
  $string = 'Foo' . $bar;
  $string = $bar . 'foo';
  $string = bar() . 'foo';
  $string = 'foo' . 'bar';
?>

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

<?php
  $string = "Foo $bar";
?>

При объединении с использованием оператора присваивания, — .= — используйте пробелы с каждой стороны оператора.

<?php
$string .= 'Foo';
$string .= $bar;
$string .= baz();
?>

[к оглавлению]

Комментарии

Комментирование файлов должно удовлетворять требованиям Doxygen. Дополнительную информацию о Doxygen можно найти здесь:

Отметьте: Drupal использует следующий синтаксис для блоков комментариев:

/**
* Comments.
*/

Все команды Doxygen должны использовать префикс @ вместо /. Комментарии общего характера — приветствуются. Общее правило их использования: если вы смотрите на код и думаете про себя — Ого! Я даже не хочу пробовать это описать, — вам это нужно обязательно описать, пока вы не забыли как это работает.

Используйте комментирование в стиле C (/* */) или в стиле C++ (//). Комментирование в стиле Perl/shell (#) — не приветствуется.

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

// Unselect all other contact categories.
db_query('UPDATE {contact} SET selected = 0');

[к оглавлению]

Подключение кода

Использование любого оператора (require_once() — безусловное, include_once() — условное) подключения файлов классов гарантирует, что файлы будут подключены только один раз. Эти операторы используют один список подключенных файлов, так что вы можете не беспокоиться о смешивании операторов подключения. Файл подключенный с помощью оператора require_once() не будет повторно подключен при использовании оператора include_once().

Отметьте: include_once() и require_once() — это операторы, не функции. Вы не должны использовать для них правила оформления функций и писать вместе с ними название файла.

При подключении кода и той же папки или подпапки, начинайте запись пути к файлу с точки:

include_once ./includes/mymodule_formatting.inc

В Drupal 7 и более поздних версиях используйте DRUPAL_ROOT:

require_once DRUPAL_ROOT . '/' . variable_get('cache_inc', 'includes/cache.inc');

[к оглавлению]

Теги PHP-кода

Для определения границ PHP-кода всегда используйте именно такую запись тегов: <?php ?> (XML-стиль, не используйте краткую запись — <? ?> — или какую-либо другую запись). Это обязательное требование Drupal, которое позволяет использовать PHP-код в разных ОС и разных условиях обработки/выполнения кода.

Отметьте: заключительная часть — ?>, должна быть опущена во всех кодовых файлах (.module, .inc и т.д.). Закрывающая часть является необязательной и её отсутствие позволяет предотвратить учёт использования ненужных пробелов в конце файла, что может вызвать проблемы в каких-нибудь системах. Дополнительная информация доступна в документе PHP Code tags.

[к оглавлению]

Точки с запятой

Язык PHP требует использования точки с запятой в конце большинства строк, но позволяет опустить их использование в конце блоков кода. Стандарты кодирования Drupal требуют использования точки с запятой всегда, даже если это конец блоков кода. В частности, точку с запятой следует использовать и в однострочных блоках:

<?php print $tax; ?>

[к оглавлению]

CVS-заголовок

Все кодовые файлы в Drupal должны содержать следующий блок комментария, с которого должен начинаться файл:

<?php
// $Id$

Этот тег будет автоматически расширен при использовании CVS до содержания в нём полезной информации, например:

<?php
// $Id: CODING_STANDARDS.html,v 1.7 2005/11/06 02:03:52 webchick Exp $

[к оглавлению]

Примеры URLs

Используйте запись example.com для всех примеров URL, как рекомендуется в RFC 2606:


3. Reserved Example Second Level Domain Names

The Internet Assigned Numbers Authority (IANA) also currently has the following second level domain names reserved which can be used as examples.

  • example.com
  • example.net
  • example.org

[к оглавлению]

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

[к оглавлению]

Функции и переменные

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

Название внутренних функций (предназначенных для локального использования в конкретном модуле) должны начинаться символом подчёркивания.

_node_get()

$this->_status

[к оглавлению]

Константы

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

[к оглавлению]

Глобальные переменные

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

[к оглавлению]

Классы

Классы именуются подобным образом — CamelCase, например:

<?php
abstract class DatabaseConnection extends PDO {
?>

методы классов и свойства именуются подобным образом — lowerCamelCase, например:

<?php
public $lastStatement;
?>

The use of private class methods and properties should be avoided -- use protected instead, so that another class could extend your class and change the method if necessary. Protected (and public) methods and properties should not use an underscore prefix, as was common in PHP 4-era code.

For more information on class and OO standards, see Object-oriented code.

[к оглавлению]

Названия файлов

Все файлы документации должны использовать расширение .txt для того, чтобы сделать их просмотр в Windows более лёгким. Название файла должно записываться в верхнем регистре, а расширение в нижнем. Примеры: README.txt, INSTALL.txt, TODO.txt, CHANGELOG.txt и т.д.

[к оглавлению]
Метки: