Стиль и синтаксис
Здесь описываются используемые правила кодирования, принятые при разработке с CodeIgniter.
Содержание
- Формат файлов
- Закрывающий тег PHP
- Названия классов и методов
- Имена переменных
- Комментарии
- Константы
- TRUE, FALSE и NULL
- Логические операторы
- Сравнение возвращаемых значений и приведение типов
- Отладка кода
- Пробелы в файлах
- Совместимость
- Названия классов и файлов с помощью общих слов
- Имена таблиц базы данных
- Один файл на класс
- Пробелы
- Разрывы строк
- Отступы в коде
- Скобки и отступы
- Локализованый текст
- Приватные методы и переменные
- Ошибки PHP
- Короткие открывающие теги
- Одно объявление на линию
- Строки
- Запросы SQL
- Аргументы по умолчанию
Формат файлов
Файлы должны сохраняться в кодировке Unicode (UTF-8). BOM НЕ должно использоваться. В отличие от UTF-16 и UTF-32, нет порядка битов для указания в файле в UTF-8, и BOM может иметь негативный эффект в PHP при отправке вывода, не позволяя приложению устанавливать собственные заголовки. Должны использоваться окончания строк Unix (LF).
Здесь описано, как применить эти настройки для некоторых из самых распространенных текстовых редакторов. Инструкции для вашего текстового редактора могут отличаться, смотрите документацию вашего текстового редактора.
TextMate
- Откройте Application Preferences
- Щелкните Advanced, и выберите закладку "Saving"
- В "File Encoding" выберите "UTF-8 (рекомендуется)"
- В "Line Endings" выберите "LF (рекомендуется)"
- Опционально: Проверьте "Use for existing files as well", если вы хотите изменить окончание строк открываемых файлов в соответствии с вашими предпочтениями.
BBEdit
- Откройте Application Preferences
- Выберите "Text Encodings" слева.
- В "Default text encoding for new documents" выберите "Unicode (UTF-8, no BOM)"
- Опционально: В "If file's encoding can't be guessed, use" выберите "Unicode (UTF-8, no BOM)"
- Выберите "Text Files" слева.
- В "Default line breaks" выберите "Mac OS X and Unix (LF)"
Закрывающий тег PHP
Закрывающий тег документа PHP ?> является опциональным для парсера PHP. Однако, если он используется, любой пробел после него будет отправлен в браузер. Это может привести к неожиданым ошибкам. ОПУСКАЙТЕ закрывающий тег PHP, и вместо этого используйте блок комментария для обозначения конца файла и корня приложения
НЕПРАВИЛЬНО:
<?php
echo "Here's my code!";
?>
ПРАВИЛЬНО:
<?php
echo "Here's my code!";
/* End of file myfile.php */
/* Location: ./system/modules/mymodule/myfile.php */
Названия классов и методов
Имена классов всегда должны начинаться с большой буквы. Если слов много, они должны разделяться подчеркиванием, и не использовать ВерблюжьюНотацию. Все другие методы класса должны быть в нижнем регистре, и называться в соответствии с их функциями, желательно вместе с глаголом. Старайтесь избегать чрезмерно длинных и подробных имен.
НЕПРАВИЛЬНО:
class superclass
class SuperClass
ПРАВИЛЬНО:
class Super_class
class Super_class {
function __construct()
{
}
}
Примеры неправильного и правильного именования:
НЕПРАВИЛЬНО:
function fileproperties() // не ясно и требуется разделитель — знак подчеркивания
function fileProperties() // не ясно и использована ВерблюжьяНотация
function getfileproperties() // Лучше! Но все еще пропущен разделитель — знак подчеркивания
function getFileProperties() // использована ВерблюжьяНотация
function get_the_file_properties_from_the_file() // многословно
ПРАВИЛЬНО:
function get_file_properties() // ясно, с прочерком, и в нижнем регистре
Имена переменных
Директивы для имен переменных сильно аналогичны правилам именования методов классов. А именно, переменные должны содержать только буквы в нижнем регистре, использовать знак подчеркивания в качестве разделителя, и достаточно ясно называться, чтобы понимались их назначение и содержимое. Очень короткие переменные, без слов, могут быть использованы только в качестве итераторов для циклов for().
НЕПРАВИЛЬНО:
$j = 'foo'; // одна буква может быть использована только в циклах for()
$Str // содержит символы в верхнем регистре
$bufferedText // использует ВерблюжьюНотацию, и может быть укорочено без потери семантического значения
$groupid // много слов без прочерка
$name_of_last_city_used // слишком длинное
ПРАВИЛЬНО:
for ($j = 0; $j < 10; $j++)
$str
$buffer
$group_id
$last_city
Комментарии
Обычно код должен быть прокомментирован добросовестно. Это не только помогает понять выполнения и задачи кода для менее опытных программистов, но окажется неоценимым, когда вы вернетесь к вашему коду спустя месяцы. Нет требуемого формата для комментариев, но нижеследующее рекомендуется.
Используйте стиль комментариев DocBlock , предваряющих декларацию классов и методов, так что они могут быть поняты и использованы IDE:
/**
* Super Class
*
* @package Package Name
* @subpackage Subpackage
* @category Category
* @author Author Name
* @link http://example.com
*/
class Super_class {
/**
* Encodes string for use in XML
*
* @access public
* @param string
* @return string
*/
function xml_encode($str)
Используйте единственную строку комментария в коде, оставляя пустую строку между большими комментариями и кодом.
// разбивайте строки
$parts = explode("\n", $str);
// A longer comment that needs to give greater detail on what is
// occurring and why can use multiple single-line comments. Try to
// keep the width reasonable, around 70 characters is the easiest to
// read. Don't hesitate to link to permanent external resources
// that may provide greater detail:
//
// http://example.com/information_about_something/in_particular/
$parts = $this->foo($parts);
Константы
Константы следуют таким же правилам, как и для переменных, за исключением того, что их имена всегда в верхнем регистре. Constants follow the same guidelines as do variables, except constants should always be fully uppercase. Всегда используйте константы CodeIgniter, когда это возможно, например SLASH, LD, RD, PATH_CACHE и так далее.
НЕПРАВИЛЬНО:
myConstant // пропущен разделитель — знак подчеркивания, и не целиком в верхнем регистре
N // нет однобуквенных констант
S_C_VER // не ясно
$str = str_replace('{foo}', 'bar', $str); // нужно использовать константы LD и RD
ПРАВИЛЬНО:
MY_CONSTANT
NEWLINE
SUPER_CLASS_VERSION
$str = str_replace(LD.'foo'.RD, 'bar', $str);
TRUE, FALSE и NULL
Ключевые слова TRUE, FALSE и NULL должны быть всегда в верхнем регистре.
НЕПРАВИЛЬНО:
if ($foo == true)
$bar = false;
function foo($bar = null)
ПРАВИЛЬНО:
if ($foo == TRUE)
$bar = FALSE;
function foo($bar = NULL)
Логические операторы
Использование || не рекомендуется, так как на некоторых устройствах вывода выглядит слишком маленьким (например, похоже на 11). && предпочтительней, чем AND но также приемлемо, и всегда должен быть пробел перед !.
НЕПРАВИЛЬНО:
if ($foo || $bar)
if ($foo AND $bar) // хорошо, но не рекомендуется из-за неудобств подстветки синтаксиса в различных приложениях
if (!$foo)
if (! is_array($foo))
CORRECT:
if ($foo OR $bar)
if ($foo && $bar) // рекомендуется
if ( ! $foo)
if ( ! is_array($foo))
Сравнение возращаемых значений и приведение типов
Некоторые функции PHP возвращают FALSE при неудаче, но могут также вернуть корректное значение в "" или 0, которое будет приравнено к FALSE в свободных сравнениях. Явное сравнение типа данных переменной при использовании возвращаемых значений в условиях позволит быть уверенным, что возвращаемое значение соответствует ожидаемому, и не является эквивалентным свободному сравнению.
Используйте такую же строгость в возвращении и проверке собственных переменных.
Используйе === и !==, если необходимо.
НЕПРАВИЛЬНО:
// Если 'foo' -
это начало строки, strpos вернет 0,
// что приведет к вычислению сравнения в TRUE
if (strpos($str, 'foo') == FALSE)
ПРАВИЛЬНО:
if (strpos($str, 'foo') === FALSE)
НЕПРАВИЛЬНО:
function build_string($str = "")
{
if ($str == "") // ой-ой! Что если FALSE или целое 0 будут переданы как аргумент?
{
}
}
ПРАВИЛЬНО:
function build_string($str = "")
{
if ($str === "")
{
}
}
Смотрите также информацию касаемо приведения типов, которая может быть очень полезной. Приведение типов имеет несколько отличный эффект, который может быть желательным.:
$str = (string) $str; // представляет $str как строку
Отладка кода
Отладочный код должен обязательно сопровождаться комментариями. Не допускается размещение отладочного кода без комметариев.
// print_r($foo);
Пробелы в файлах
Не должно быть пустого места перед открывающим тегом PHP, или следом за закрывающим тегом PHP. Вывод буферизуется, поэтому пустые места в ваших файлах могут спровоцировать несанкционированный вывод, что приведет к появлению ошибок. В примере ниже выделите текст мышкой, чтобы увидеть некорректное пустое место.
НЕПРАВИЛЬНО:
<?php
// ...пустая строка перед открывающим тегом инициирует вывод
// также и после закрывающего тега
?>
ПРАВИЛЬНО:
<?php
// нет пустого места перед открывающим и после закрывающего тегов PHP
?>
Совместимость
Если конкретно не упоминается в документации к вашим аддонам, весь код должен быть совместим с версией PHP 4.3+. К тому же, не используйте функции PHP, которые требуют библиотек, не присутствующих по умолчанию и требующих установки, если ваш код не поддерживает альтернативные методы, в случае недоступности этих функций. В противном случае однозначно документируйте свои требования.
Имена классов и файлов, использующие общеупотребительные слова
Если ваш класс или имя файла названы общеупотребительным словом, или возможно называются как другой PHP скрипт, используйте уникальный префикс для того, чтобы предотвратить коллизии. Всегда понимайте, что ваши пользователи могут запустить ваш скрипт с другими приложениями. Использование префикса позволяет однозначно идентифицировать вас как разработчика или компанию..
НЕПРАВИЛЬНО:
class Email pi.email.php
class Xml ext.xml.php
class Import mod.import.php
ПРАВИЛЬНО:
class Pre_email pi.pre_email.php
class Pre_xml ext.pre_xml.php
class Pre_import mod.pre_import.php
Имена таблиц базы данных
Любые таблицы, которые использует ваша программа, должны иметь префикс 'exp_', а также префикс, идентифицирующий вас как разработчика или компанию, и краткое описательное имя таблицы. Вы не должны беспокоиться насчет префикса, использованного в пользовательской инсталляции, так как класс CodeIgniter для работы с базами данных автоматичеки конвертирует 'exp_' в то, что актуально используется.
НЕПРАВИЛЬНО:
email_addresses // пропущены оба префикса
pre_email_addresses // пропущен префикс exp_
exp_email_addresses // пропущен уникальный префикс
ПРАВИЛЬНО:
exp_pre_email_addresses
ПРИМЕЧАНИЕ: Будьте внимательны к тому, что MySQL имеет ограничение в 64 символа для имен таблиц. Это не должно стать проблемой, так как имена таблиц, превышающие это ограничение, явно необоснованно велики. Например, следующее имя таблицы превышает это ограничение на один символ. Глупо, не так ли? exp_pre_email_addresses_of_registered_users_in_seattle_washington
Один файл на класс
Используйте раздельные файлы для каждого класса, даже если классы тесно связаны.
Пробелы
Используйте табы для создания отступов, а не пробелы. Это может выглядеть незначительным, но использование табов вместо пробелов позволяет разработчику смотреть на ваш код с отступами, которые они предпочитают и настраивают их в своем приложении. Как дополнительное преимущество, файлы с табами более компактны, так как символ таба занимает меньше места, чем несколько пробелов.
Разрывы строк
Файлы должны сохраняться с окончаниями строк Unix. Этот вопрос больше к "разработчикам", которые работают в Windows, но в любом случае убедитесь, что ваш тектовый редактор настроен правильно.
Отступы
Используйте отступы в стиле Allman. За исключением декларации класса, скобки должны присутствовать по одной на строке, и отступы должны соответствовать контролирующему условию.
НЕПРАВИЛЬНО:
function foo($bar) {
// ...
}
foreach ($arr as $key => $val) {
// ...
}
if ($foo == $bar) {
// ...
} else {
// ...
}
for ($i = 0; $i < 10; $i++)
{
for ($j = 0; $j < 10; $j++)
{
// ...
}
}
ПРАВИЛЬНО:
function foo($bar)
{
// ...
}
foreach ($arr as $key => $val)
{
// ...
}
if ($foo == $bar)
{
// ...
}
else
{
// ...
}
for ($i = 0; $i < 10; $i++)
{
for ($j = 0; $j < 10; $j++)
{
// ...
}
}
Скобки и отступы
Обычно, круглые и фигурные скобки не используют дополнительные пробелы. Исключением являются пробелы перед контролирующими структурами PHP, которые принимают аргументы в скобках (declare, do-while, elseif, for, foreach, if, switch, while), чтобы помочь отличить их от функций и увеличить читаемость.
НЕПРАВИЛЬНО:
$arr[ $foo ] = 'foo';
ПРАВИЛЬНО:
$arr[$foo] = 'foo'; // no spaces around array keys
НЕПРАВИЛЬНО:
function foo ( $bar )
{
}
ПРАВИЛЬНО:
function foo($bar) // no spaces around parenthesis in function declarations
{
}
НЕПРАВИЛЬНО:
foreach( $query->result() as $row )
ПРАВИЛЬНО:
foreach ($query->result() as $row) // одиночный пробел после контролирующей структуры PHP, но не внутри скобок
Локализованный текст
Любой текст, который выводится из контрольной панели, должен иметь языковую переменную в вашем языковом файле, для обеспечения локализации.
НЕПРАВИЛЬНО:
return "Invalid Selection";
ПРАВИЛЬНО:
return $this->lang->line('invalid_selection');
Приватные методы и переменные
Методы и переменные, которые доступны только внутри вашего класса, такие как утилиты и функции-помощники, которые помогают публичным методам использовать абстракцию кода, должны начинаться со знака подчеркивания в качестве префикса.
convert_text() // публичный метод
_convert_text() // приватный метод
ошибки PHP
Код должен работать безошибочно и не зависеть от предупреждений и уведомлений. Например, никогда не работайте с переменной, которую вы не устанавливали самостоятельно (такие как ключи массива $_POST) без предварительной проверки isset().
Убедитесь, что в процессе разработки вашего приложения вывод ошибок включен для ВСЕХ пользователей, и display_errors включено в окружении PHP. Вы можете проверить эту установку:
if (ini_get('display_errors') == 1)
{
exit "Enabled";
}
На некоторых серверах display_errors выключено, если вы не имеете возможность изменить это в php.ini, вы можете включить вывод ошибок самостоятельно:
ini_set('display_errors', 1);
ПРИМЕЧАНИЕ: Установка display_errors с ini_set() при выполнении не идентична установке в окружении PHP. В частности, это не будет иметь эффекта в случае, если скрипт производит фатальную ошибку.
Короткие открывающие теги
Всегда используйте полные открывающие теги PHP, так как некоторые серверы могут иметь выключенную опцию short_open_tag.
НЕПРАВИЛЬНО:
<? echo $foo; ?>
<?=$foo?>
ПРАВИЛЬНО:
<?php echo $foo; ?>
Одно объявление на строке
Никогда не комбинируйте объявление на одной строке.
НЕПРАВИЛЬНО:
$foo = 'this'; $bar = 'that'; $bat = str_replace($foo, $bar, $bag);
ПРАВИЛЬНО:
$foo = 'this';
$bar = 'that';
$bat = str_replace($foo, $bar, $bag);
Строки
Всегда используйте строки в одиночных кавычках, если вы не нуждаетесь во внутренней обработке переменных. И в случаях, если вы нуждаетесь в парсинге, обязательно используйте скобки, чтобы предотвратить жадный парсинг ключей. Вы также можете использовать двойные кавычки, если используете экранирующие символы.
НЕПРАВИЛЬНО:
"My String" // нет переменных для парсинга, следовательно, нет смысла в двойных кавычках
"My string $foo" // нужны скобки
'SELECT foo FROM bar WHERE baz = \'bag\'' // уродливо
ПРАВИЛЬНО:
'My String'
"My string {$foo}"
"SELECT foo FROM bar WHERE baz = 'bag'"
Запросы SQL
Ключевые слова MySQL всегда в верхнем регистре: SELECT, INSERT, UPDATE, WHERE, AS, JOIN, ON, IN, etc.
Разбивайте длинные запросы на строки для читабельности, предпочтительно по одной инструкции на строку.
НЕПРАВИЛЬНО:
// ключевые слова в нижнем регистре и запрос слишком длинный
// для одной строки
$query = $this->db->query("select foo, bar, baz, foofoo, foobar as raboof, foobaz from exp_pre_email_addresses where foo != 'oof' and baz != 'zab' order by foobaz limit 5, 100");
ПРАВИЛЬНО:
$query = $this->db->query("SELECT foo, bar, baz, foofoo, foobar AS raboof, foobaz
FROM exp_pre_email_addresses
WHERE foo != 'oof'
AND baz != 'zab'
ORDER BY foobaz
LIMIT 5, 100");
Аргументы по умолчанию
В соответствующих случаях, указывайте в определениях функций значения по умолчанию, которые помогут предотвратить ошибки PHP при ошибочных вызовах, и помогают уменьшить количество кода, при использовании функции. Пример:
function foo($bar = '', $baz = FALSE)