Стиль написания кода

На самом деле, нет никаких строгих правил форматирования программного кода, но всё же следует придерживаться некоторых принципов при добавлении кода в «Докувики».

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

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

if ($foo == "bar"){
  call_bar();
}elseif($foo == "baz"){
  call_baz();
}else{
  call_other();
}

Строка должна заканчиваться единственным символом перевода строки LF (так называемый, стиль UNIX). Пожалуйста, избегайте пробелов в конце строки. Заглянув в мой файл vimrc вы сможете понять, как легко в редакторе VIM придерживаться этого автоматически.

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

Пример:

/**
 * Check for foo in bar
 *
 * Checks if there is a foo in bar
 *
 * @author   Joe Schmoe <joe@example.com>
 * @param    string $in your input
 * @returns  boolean    true if foo in bar
 *
 */
function is_foo($in){
...
}

Эти комментарии используются для автоматической генерации документации по API.

Вам следует опускать закрывающие тэги PHP (?>) в конце всех php-файлах, чтобы избежать нежелательного вывода. Это может показаться странным, но, на самом деле, это отмечается в руководстве по PHP:

Замечание: Закрывающие теги блока PHP в конце файла не обязательно, и в некоторых случаях их отсутствие даже полезно, когда используются функции include() или require(), таким образом, нежелательные пробелы не возникнут в конце файла, и у вас все еще будет возможность добавлять заголовки (с помощью функции header()). Кроме того, это удобно, если вы используете буферизацию вывода, и не хотите добавлять нежелательные пробелы в конце части, сгенерированной включаемым файлом.