Урок - Стандарты кодирования в Drupal6.

Главная » Курсы » Курс Drupal 6, Разработка модулей. » Урок - Стандарты кодирования в Drupal6.

Обучающий онлайн курс
Drupal 6, Разработка модулей.

Лицензия: Копирование запрещено.

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

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

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

Операторы

Двоичные операторы: +, -, =, !=, ==, >(и т.п.) должны отделяться одиночным пробелом слева и справа от оператора (для удобства чтения).

Например:

$foo = $bar;
вместо:
$foo=$bar;

Единичные операторы ++, --, ! должны идти без пробела с операндом:

$foo++;
вместо:
$foo ++;

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

Необходимо ихспользовать пробел между (типом) и $переменной:

(int) $number;
вместо
(int)$number;

Конструкции

Правило для использования if, elseif, for, while, switch и т.д.

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

if ( $condition) {
  // action 1;
}
elseif ($condition2 && $condition3) {
  // action2;
}
else {
  // default action;
}

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

switch (condition) {
  case 1:
    // action 1;
    break;
  case 2:
    // action 2;
    break;
	// ...
  default:
    //	default action;
    break;
}

Для конструкции do-while:

do {
  // action;
} 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:

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

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

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

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

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

_node_get()
<p>$this->_status</p>

Константы

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

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

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

Классы

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

<?php
abstract class DatabaseConnection extends PDO {
?>

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

<?php
public $lastStatement;
?>

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

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