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

Отметьте: Стандарты кодирования Drupal основаны на PEAR Coding standards.

TOC [hide]

Отступы
Конструкции
Вызов функций
Объявление функций
Массивы
Комментарии
Подключение кода
Теги PHP-кода
Заголовок блока комментария
Примеры URLs
Названия (правила именования)

Отступы

Отступы создаются 2 пробелами. Табуляция не используется.

Конструкции

Это правило включает использование 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; }

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

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

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

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

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

$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];
}

Массивы

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

$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.'),
);

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

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

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

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

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

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

Теги PHP-кода

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

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

Заголовок блока комментария

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

<?php
// $Id$

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

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

Примеры URLs

Используйте запись: example.com для всех примеров URLs, как рекомендуется в 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

Константы

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

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

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

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

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